XVM/RSX PART V 
SYSTEM DIRECTIVES 



CHAPTER 1 
INTRODUCTION TO SYSTEM DIRECTIVES 



1.1 FUNCTION OF SYSTEM DIRECTIVES 

RSX user Tasks carry on communication with the Executive by means of 
System Directives which perform such functions as scheduling and 
rescheduling Task execution, suspending and resuming a Task, 
connecting to an interrupt line, and fixing a Task in core. Most 
Directives can be issued in any of the following ways: 

. by the user from within a FORTRAN IV Task 

. by the user from within a MACRO Task 

. by the operator via the Monitor Console Routine 



1.2 DESCRIPTION OF DIRECTIVES 

System Directives are implemented as CAL instructions. These are 
machine language instructions that transfer control from anywhere in 
core to the monitor via fixed-memory locations. Each CAL instruction 
takes a parameter block as an operand: the instruction's address 
field points to the first word of the associated block of parameters. 
This block consists of one or more words of contiguous core and is 
called a CAL Parameter Block (CPB) . 

Most System Directives can be executed directly from MACRO programs. 
When a System Directive is issued by a FORTRAN program, the program 
CALLS one of a series of FORTRAN Library Routines; the routine then 
issues the Directive. Monitor Console Routine (MCR) Function Tasks 
issue direct calls for specific System Directives. Exact procedures 
for invoking System Directives are discussed in subsequent sections of 
this manual. Table 1-1 contains a list of all System Directives 
implemented under RSX. 
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1.3 PROCESSING A DIRECTIVE 

When RSX processes a system directive, control is passed to a 
reentrant CAL Dispatch Routine. This routine takes the low-order six 
bits of the first CPB word as an octal CAL function code and, using 
this code as an index, transfers control to a particular CAL service 
routine. After the CAL service routine has performed the operation 
requested by the directive, it passes control to a CAL Exit Routine, 
which returns control to the directive-issuing task. Execution of 
this task continues at the location immediately followinq the CAL 
instruction. 



NOTE 

To minimize Monitor overhead, registers 

such as AC, MQ and XR are neither saved 

nor restored when a CAL instruction is 
executed. 

The CAL Dispatch Routine and many CAL service routines are reentrant. 
This feature allows an interrupt service routine to issue Monitor 
requests without waiting for completion of a request issued by a task. 

Most system directives take an event variable in the MACRO or FORTRAN 
call. With few exceptions, inclusion of this event variable is 
optional. If an event variable is specified, a completion code 
indicating the status of the directive is returned to the issuing 
task. A code of zero means that the directive is pending, a positive 
code means that it has been completed successfully, and a negative 
code means either that it has not been accepted or that it has been 
completed, but an error has occurred. The value of the negative code 
indicates the particular fault. 



1.4 DIRECTIVE ERRORS 

Before attempting to perform the operation requested by the directive 
call, the CAL service routine checks for a variety of serious errors. 
Following are possible errors it detects during this initial check: 

1. Executing a CAL, such as XCT (CAL CPBADR) . 

2. CPB with illegal function code (one not included in Table 
1-1). 

3. Event variable address outside the task area. This check is 
made only for tasks built in user mode. 
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4. CPB address outside the task area. This check is made only 
for tasks built in user mode. 

In general, verification checks on address parameters are performed 
for user-mode tasks, but not for exec-mode tasks. Other errors may be 
detected during actual performance of the operation. The number of 
ignored CALs is logged as a performance indicator or debugging aid in 
SCOM location 151 (octal) in the Executive. 

If one of the above errors is detected, the issuing task is terminated 
(forced to exit) and a task termination notice with the following 
format is printed: 

BAD CAL AT PC = Xyyyyy 

In this format, Xyyyyy is an 18-bit word in which X identifies the 
task status with the following three bits: 

Bit Meaning 

Contents of link 

1 Addressing mode: = page 
mode; 1 = bank mode 

2 Protection mode: = exec 
mode; 1 = user mode 

In the above format, yyyyy is a 15-bit address indicating the location 
of the error. For user-mode tasks, this address is relative to the 
partition base. 

For tasks requested on behalf of a MULTIACCESS user, the termination 
notice is printed on the user terminal. For all other tasks, the 
message is sent to the device assigned to system LUN-3. 

The MULTIACCESS Exit Processor controls the printing of abnormal task 
termination messages for all tasks run under control of that Monitor. 
To cause printing of this task termination notice for all other tasks, 
an entry is made in the Task Termination Notice Request List (TNRL) 
and a disk-resident task named TNTERM is requested by the system. 



1.5 DIRECTIVE CONVENTIONS 

System directives are constructed according to conventions that differ 
slightly for MACRO and FORTRAN calls but basically consist of the 
following : 

1. The system directive name is followed by a space in the 
calling line. 

2. All parameters included in the call are separated by commas. 

3. FORTRAN parameters are enclosed in parentheses. 

4. Rules about line termination and error correction conform to 
MACRO or FORTRAN program standards. 
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5, In "form" models, upper-case characters (except LUN) indicate 
those entries required by the system. Lower-case characters 
indicate entries that are to be specified by the user and are 
dependent on the particular task. 

6. "MACRO call" refers to entries in the MACRO definition file 
(RMC.13 SRC). This file is usually not used when assembling 
MACRO programs, because the MACRO definitions increase the 
size of the resulting binary file. 

Table 1-1 summarizes legal calls to all RSX system directives. 



Table 1-1 
System Directives 



CAL Code 










(octal) 


MACRO Call 


FORTRAN Call 


MCR Call 


Internal 


00 


I/O calls 


I/O calls 


__- 


.-_ 


01 


REQUEST 


CALL REQST 


REQfUEST] 


— 


02 


SCHEDULE 


CALL SCHED 


SCHfEDULE] 


— 


03 


RUN 


CALL RUN 


RUN 


— 


04 


CANCEL 


CALL CANCEL 


CAN[CEL] 


___ 


05 


WAIT 


CALL WAIT 





— 


06 


SUSPEND 


CALL SUSPND 





— 


07 


RESUME 


CALL RESUME 


RES[UME] 


— 


10 


EXIT 


CALL EXIT 


See ABORT 


— - 


11 


CONNECT 


— - 








12 


DISCONNECT 








— 


13 


MARK 


CALL MARK 


— — - 





14 


SYNC 


CALL SYNC 


SYN[C] 


— _ 


15 


FIX 


CALL FIX 


FIX 


— 


16 


UNFIX 


CALL UNFIX 


UNF[IX] 


— 


17 











SETJEA 


20 


WAITFOR 


CALL WAITFR 


— _ 





21 


DISABLE 


CALL DISABL 


DIS[ABLE] 





22 


ENABLE 


CALL ENABLE 


ENA[BLE] 





23 


UNMARK 


CALL UNMARK 





UNMARK 


24 


DATE 


CALL DATE 


DAT[E] 





25 








___ 


TSKNAM 


26 











PARINF 


27 











RAISES 


30 











RASP 


31 





CALL SPY 


— - 





32 





CALL SPYSET 








33 





CALL QJOB 








34 





CALL EXECUT 


XQT 





35 





CALL SHARE 


— -.~ 





36 











REQMAP 


37 


■ 


^""^ 


— — — 


XFRCMD 
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CHAPTER 2 
SYSTEM DIRECTIVES 



Each of the following sections describes one System Directive. In all 
models emd examples, the following conventions apply: 

1. A space in the text indicates an actual space in the 
Directive call, 

2. Square brackets ([]) indicate optional parameters. 

3. In "Form" models, upper case characters indicate those 
required by the system, while lower case characters indicate 
entries which are to be specified by the user and are 
dependent on his particular Task. 
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CANCEL 



2.1 CANCEL: CANCELLING REQUESTS FOR A TASK 

The CANCEL Directive instructs RSX to CANCEL all scheduled requests 
(Clock Queue entries made by SCHEDULE, RUN, or SYNC) for activation of 
a particular Task by nullifying those requests in the Clock Queue. 
CANCELlation affects neither future scheduling of a Task (as DISABLE 
does) , nor its current execution. The user can optionally include an 
Event Variable in the Directive. Note that Task CANCELlation does not 
remove any nodes from the Clock Queue. Nodes are removed only when 
the time given in the node comes due. 

CANCEL Directives can be issued by MACRO and FORTRAN programs, but not 
by interrupt service routines. A Task cannot CANCEL itself. The 
MACRO call has the following form: 



Form: 


CANCEL name [ ,ev] 


Where: 


name of Task CANCELled is a string of 

one to six .SIXBT characters 
ev is the Event Variable address 


Example : 


CANCEL SCAN,EV 



The FORTRAN call has the following form: 



Form: 


CALL CANCEL (nHname [ ,ev] ) 


Where: 


n is the number of characters in name 
name of Task CANCELled is a string of 

one to five ASCII characters 
ev is the integer Event Variable 


Example: 


CALL CANCEL (4HSCAN,IEV) 



The CANCEL Directive can also be called from the Monitor Console 
Routine . 

The CPB for this Directive consists of the following: 



Word 

1 
2 
3 



Contents 
CAL function code (04) 
Event Variable address 
Task name (first half) 
Task name (second half) 
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If the Directive is rejected by RSX, the Event Variable (if specified) 
is set to one of the following to indicate rejection and its cause: 

Event Variable Meaning 

-201 Task not in system 

If the CANCEL is accepted, the Event Variable (if specified) is set to 
+1, and all scheduling nodes in the Clock Queue for this Task are 
nullified. Following is an example of a CANCEL CPB: 

CPB 04 /CAL PARAMETER BLOCK TO CANCEL 

EV /ALL SCHEDULE REQUESTS FOR THE 

.SIXBT "T7@(a@ia" /TASK "T7". 
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CONNECT 



2.2 



CONNECT: CONNECTING TO AN INTERRUPT LINE 



The CONNECT Directive instructs RSX to transfer control to a 
particular location (entry point) whenever an interrupt occurs on an 
indicated interrupt line. In effect, this creates a link between a 
specific Automatic Priority Interrupt (API) trap address amd a 
specific entry point to am interrupt service routine. One trap 
address exists for each of the 32 API lines supplied on the computer. 
The following list does not include device lines that are always 
CONNECTed to the system (e.g.. Clock, Disk, aind Teletype keyboards emd 
printers). Line numbers cibove 37 octal are pseudo-API lines, simulated 
by the Executive for devices connected only to the Program Interrupt 
(PI). 

The user Ccin optionally include an Event Variable in the Directive. 

Additional DECtape (line 36) or an additional Dataphone (line 37) 
cannot be added without modifications to the Handlers for these 
devices. 



CONNECT Directives can be issued by MACRO programs 
way: 



in the following 



Form: 


CONNECT line, entry [,ev] 


Where: 


line is an octal number representing the 
interrupt line to be CONNECTed 

entry is the entry address of the related 
interrupt service routine 

ev is the Event Variable address 


Example : 


CONNECT an interrupt service routine for 
an A/D Converter at entry point ADINT to 
interrupt line 17 : 

CONNECT 17, ADINT, ADEV 



Because FORTRAN is not an appropriate language for writing 
interrupt-handling routines, no FORTRAN call is included. Connects 
cannot be issued from the Monitor Console Routine. 

The CPB for this Directive consists of the following; 



Word 



Contents 



CAL function code (11) 

1 Event Variable address 

2 Interrupt line number 

3 Interrupt transfer address 
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Table 2-1 
API Lines 


Octal Line Number 


Device 


00 ,/ q. 


Software level 4 


01 


Software level 5 


02 


Software level 6 


03 


Software level 7 


04 


DECtape 


05 


Magtape 


06 


(Unused) 


07 


Disk Cartridge (RK-UC15 Unichannel) 


10 


Paper Tape Reader 


11 


Clock overflow 


12 


Power failure 


13 


Memory parity error 


14 


Display (and reserved for VP storage 
scope) 


15 


Card Reader 


16 


Line Printer 


17 


Analog-to-Digital Converter 


20 


DB9 9A-DB98A Interprocessor Buffer 


21 


(Unused) 


22 


Dataphone 


23 


Fixed-head disk (RF) 


24 


Disk Pack (RP) 


25 


xy Plotter 


26 


(Unused) 


27 


(Unused) 



(Continued on next page) 
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Table 2-1 (Cont.) 
API Lines 



Octal Line Nvunber 


Device 


30 


(Unused) 


31 


(Unused) 


32 


(Unused) 


33 


(Unused) 


34 


LT19 Output 


35 


LT19 Input 


36 


Additional DECtape 


37 


Additional Dataphone 


40 


Console Teletype Printer 


"'\ r' 41 


Console Teletype Keyboard 


42 


Paper Tape Punch 


43 


Memory-protect violation 
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If the CONNECT Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause: 



Event Variable Meaning 

-26 Illegal Function for a USER-mode Task 

-301 Illegal line number 

-302 Indicated line already CONNECTed 



If the CONNECT Directive is accepted, the Event Variable 
specified) is set to +1 and the CONNECTion is established. 

Following is an example of a CONNECT CPB; 



(if 



CPB 11 

EV 
4 

DTINT 



/CAL PARAMETER BLOCK TO CONNECT THE 
/DECTAPE INTERRUPT (LINE #4) TO THE 
/LOCATION "DTINT". 
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2,3 



DATE: RETRIEVING TIME AND DATE 



The DATE Directive instructs RSX to return the current date and time 
to the issuing Task. This information is obtained from the system's 
internal clock and calendar. The Directive can be issued by MACRO and 
FORTRAN programs and by interrupt service routines. The user can 
optionally include an Event Variable in the Directive. Following is 
the MACRO call: 



Form: 


DATE month, day, year, hour, minute, second [,ev] 


where: 


month is an integer in range 1-12 decimal 
day is an integer in range 1-31 decimal 
year is an integer in range 0-99 decimal and 

represents the last two digits of the calendar 

year 
hour is an integer in range 0-23 decimal 
minute is an integer in range 0-59 decimal 
second is an integer in range 0-59 decimal 
ev is the Event Variable address 


Example : 


DATE MON,DAY,YR,HR,MI,SEC,EV 



and the FORTRAN call: 



Form: 


CALL DATE(d) 


Where: 


d is an array consisting of six integer words: 

d(l) = month in range 1-12 decimal 

d(2) = day in range 1-31 decimal 

d(3) = year in range 1-99 decimal; represents 

the last two digits in the calendar year 
d(4) = hour in range 0-23 decimal 
d(5) = minute in range 0-59 decimal 
d(6) = second in range 0-59 decimal 


Example: 


DIMENSION IDATE(6) 

• 
• 

CALL DATE(IDATE) 



This Directive can also be called from the Monitor Console Routine. 
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The CPB for this Directive consists of the following: 



Word Contents 

CAL function code (24) 

1 Event Variable address 

2 Month buffer (1-12) 

3 Day buffer (1-31) 

4 Year buffer (0-99) 

5 Hour buffer (0-23) 

6 Minute buffer (0-59) 

7 Second buffer (0-59) 

The Event Variable (if specified) is always set to +1. The date and 
time are stored in CPB words 2 through 7 . 

Following is an example of a DATE CPB : 

CPB 24 /CAL PARAMETER BLOCK 

EV /TO OBTAIN DATE 

•BLOCK 6 /AND TIME. 
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DISABLE 



2.4 



DISABLE: DISABLING A TASK 



The DISABLE Directive instructs RSX to reject all future REQUEST, 
SCHEDULE, RUN, FIX, and SYNC Directives for a particular Task. It 
does not have the effect of CANCEL, for it does not affect current 
activity: if rescheduling is already in effect, the Clock Interrupt 
Service Routine periodically requests the Task. If a Task has been 
DISABLEd, it is capable of responding only to the ENABLE Directive. 
If the Task is active when the DISABLE is issued, it continues to 
execute; however, all subsequent requests for the Task are ignored. 
A DISABLEd Task is not automatically deleted from the system. Only 
the REMOVE function can do this. The user can optionally include an 
Event Variable in the Directive. 

DISABLE Directives can be issued by MACRO and FORTRAN programs and by 
interrupt service routines. Following is the MACRO call: 



Form: 


DISABLE name[,ev] 


Where: 


name of Task DISABLEd is a string of 

one to six .SIXBT characters 
ev is the Event Variable address 


Example: 


DISABLE SCAN,EV 



and the FORTRAN call: 



Form: 


CALL DISABL(nHname[,ev]) 


Where: 


n is the nvimber of characters in name 
name of Task DISABLEd is a string of 

one to five ASCII characters 
ev is the integer Event Variable 


Example: 


CALL DISABL(4HSCAN,IEV) 



The DISABLE Directive can also be called from the Monitor Console 
Routine . 
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The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (21) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 

If the DISABLE Directive is rejected by RSX, the Event Variable (if 
specified) is set to the following to indicate rejection and its 
cause : 

Event Variable Meeuiing 

-201 Task not in system 

If the DISABLE Directive is accepted, the Event Variable (if 
specified) is set to +1 and the Task is DISABLEd. 

Following is an example of a DISABLE CPB: 

CPB 21 /CAL PARAMETER BLOCK 

EV /TO DISABLE TASK "Til". 

.SIXBT "Tll@@ia" 
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DISCONNECT 



2.5 



DISCONNECT: DISCONNECTING FROM AN INTERRUPT LINE 



The DISCONNECT Directive instructs RSX to nullify a CONNECT. Thus, 
when an interrupt occurs on an indicated interrupt line, RSX no longer 
transfers control to an indicated location (entry point) of a 
particular interrupt service routine. The I/O Handler for the 
relevant device ensures that all I/O transfers have been completed 
before the DISCONNECT is accepted. The user can optionally include an 
Event Variable in the Directive. 

DISCONNECTS can be issued by MACRO programs in the following way: 



Form; 


DISCONNECT line, entry t,ev] 


Where: 


line is an octal number representing 
the connected interrupt line 

entry is the entry address of the 
related interrupt service routine 

ev is the Event VaricUale address 


Example : 


DISCONNECT the A/D Converter from 

interrupt line 17: 
DISCONNECT 17 ,ADINT,ADEV 



Because FORTRAN is not an appropriate language for writing 
interrupt-handling routines, no FORTRAN call is included. DISCONNECTS 
cannot be issued from the Monitor Console Routine. 

The CPB for this Directive consists of the following: 



Word Contents 

CAL function code (12) 

1 Event Variable address 

2 Interrupt line number 

3 Current interrupt transfer address 
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If the DISCONNECT Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause : 

Event Variable Meaning 

-26 Illegal function for a USER-Mode Task 

-301 Illegal line number 

-302 Line not connected as indicated 

If the DISCONNECT Directive is accepted, the Event Variable (if 
specified) is set to +1 and the DISCONNECT is performed. 

Following is an example of the DISCONNECT CPB: 

CPB 12 /CAL PARAMETER BLOCK TO DISCONNECT 
EV /LINE #4 (DECTAPE) FROM "DTINT". 
4 
DTINT 
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ENABLE 



2.6 



ENABLE: REENABLING A TASK 



The ENABLE Directive instructs RSX to reENABLE a disabled Task, 
user C2in optionally include an Event Variable in the Directive. 



The 



This Directive can be issued by MACRO and FORTRAN programs and by 
interrupt service routines. Following is the MACRO call: 



Form: 


ENABLE neune [ ,ev] 


Where: 


name of Task ENABLEd is a string of 

one to six .SIXBT characters 
ev is the Event Variable address 


Exeunple : 


ENABLE SCAN,EV 



and the FORTRAN call: 



Form: 


CALL ENABLE (nHname [ ,ev] ) 


Where: 


n is the number of characters in name 
name of Task ENABLEd is a string 

of one to five ASCII characters 
ev is the integer Event Variable 


Example : 


CALL ENABLE (4HSCAN,IEV) 



The ENABLE Directive can also be called from the Monitor Console 
Routine. 

The CPB for this Directive consists of the following: 



Word Contents 

CAL function code (22) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 
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If the ENABLE Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause: 



Event Variable Meaning 

-201 Task not in system 

-212 Partition for Task's STL node lost because of 
reconfiguration 

-213 Partition assigned to Task currently being 
reconfigured 

If the ENABLE Directive is accepted, the Event Variable (if specified) 
is set to +1 and the Task is ENABLEd. 

Following is an example of an ENABLE CPB: 

CPB 22 /CAL PARAMETER BLOCK 

EV /TO ENABLE TASK "T12". 

.SIXBT "T12@@@" 



V-2-15 



EXECUTE 



2.7 EXECUTE: REQUESTING TASK EXECUTION FROM A USER DISK 

The EXECUTE directive allows the user to request execution of a 
that is stored in core-image form on a "user" disk. 



task 



A new task priority can be specified in the EXECUTE directive. If a 
new priority is omitted, the priority specified at task-building time 
is used. 

As options, a memory partition and an event variable can be specified 
in the directive. If the directive is issued by a MACRO program, two 
additional options can be specified: "alias execute" and "deferred 
execute" . 

The standard EXECUTE directive functions internally by: 

1. Inserting a node in the Execute List (EXELH) for the 
requested task. 

2. Requesting the task named FININS. 
FININS: 



Picks a node off of the EXELH. 
EXECUTE directive exits. 



If the list is empty, the 



Locates a created file with the name specified in the EXECUTE 
command in the disk directory associated with the specified 
LUN. 

Requests the task (if its node is in the STL) or allocates 
sufficient space on the system disk and transfers the file to 
the system disk. 

For exec-mode tasks, ensures that the specified partition 
name corresponds to the partition and base address indicated 
for the task at task-building time. For user-mode tasks, the 
partition specified at task-building time can be overridden 
by an explicit declaration, but this EXECUTE partition 
specification is not required. For both exec-mode and 
user-mode tasks, a check is performed to ensure that the task 
image fits in the partition. 

Enters a node in the STL for the task, setting a 
"remove-on-exit" bit and a bit indicating that the task has 
been run at least once ("done" bit). 
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Periodically, a task called AUTORM checks the STL and removes all 
tasks from the system disk that: 

a. Are not active 

b. Have the "done" bit set 

c. Have the "remove-on-exit " bit set 

This periodic check and removal allows substantial conservation of 
space on the disk. If, however, a task is running or has been 
scheduled by a directive such as SCHEDULE or SYNC, AUTORM does not 
remove it until a later check. 

The events listed to this point are modified slightly by selecting the 
deferred-execute option. 

If the EXECUTE directive is rejected by RSX, the event variable (if 
specified) is set to one of the following values to indicate rejection 
and the cause: 

Event Variable Meaning 

Task is not in the system 

Task is already or still active 

Task is disabled 

Illegal task priority 

Partition for the task STL node was lost 
through reconfiguration 

-213 Partition assigned to the task is 

currently being reconfigured 

-777 Deque node (for ATL) is not available 

(POOL empty) 

If the directive is accepted, the event variable (if specified) is set 
to +1. 



-201 


-202 


-204 


-206 


-212 
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EXECUTE directives may be issued by FORTRAN and MACRO programs, and 
can also be called from the Monitor Console Routine (refer to Part IV 
of this manual) . 



The FORTRAN call is of the following forr 



Form: 



Where; 



CALL XOT(nHname,p,LUN,mHpartnamt,ev] ) 



Example : 



n is the number of characters in the task name 
name of task EXECUTEd is a strinq of 

one to five ASCII characters 
p is an integer priority in decimal range 0-512 
LUN is an integer representing the logical unit 

number associated with the user disk 
m is the number of characters in partition name 
partnam is the name of the partition in 

which the task should be run 
ev is the integer event variable 



Request EXECUTion of TTIN in partition TDV at 
priority 20: 

IP = 20 

CALL XQT (4HTTIN,IP,8,3HTDV,IP,IEV) 



The requested task is made active at priority P (or at the default 
priority, if p is omitted or zero) . If a task with mapped LUNs (such 
as a MULTIACCESS task) issues an EXECUTE directive, the virtual LUN 
specified is mapped into the corresponding system LUN. 

The CAL parameter block (CPB) for this directive consists of the 
following: 



Word 

1 
2 
3 
4 
5 

6 

7 
10 
11 



Contents 

CAL function code (34) 

Event variable address 

Task name (first half) 

Task name (second half) 

Priority 

LUN, "alias execute" bit and 
bit 



"deferred execute" 



Partition name (first half) or task event variable 
address 

Partition name (second half) 

Unused or secondary task name (first half) 

Unused or secondary task name (second half) 

The alias-execute option is specified by setting bit of CPB word 5, 
which contains the LUN. When this option is specified, words 10 and 
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11 of the CPB are taken to be a secondary task name. FININS replaces 
the primary task name with the secondary task name when it prepares a 
node for insertion into the STL. Any time after the node is inserted 
into the STL, FININS requests the task using the secondary task name. 
FININS always uses the primary task name when searching disk file 
directories for the constructed file. However, if the alias-execute 
option IS specified, FININS first scans the STL using the secondary 
task name to see if the file is already installed in the system. 

The deferred-execute option is specified by setting bit 1 of CPB word 
5. When this option is specified, word 6 of the CPB is taken to be 
the address of a special "task" event variable instead of the first 
half of a partition name. FININS sets the task event variable to the 
address of the task STL node. When creating the task STL node, FININS 
zeros the pointer to the task PBDL node (word 5) and sets the 
partition-lost-through-reconf iguration" bit (bit 4 of word 4) . 
FININS attempts to locate and transfer the task image to the system 
disk as usual, but does not request the task. 

The result of these actions by FININS is to prepare a task for 
execution later when an appropriate partition has been selected. This 
feature is used primarily by MULTIACCESS. 

If FININS detects an error, it sets the task event variable to one of 
the following values: 

Meaning 

Illegal LUN specified 

HINF error 

Illegal device specified 

Disk dismounted 

GET error 

File was not created 

File was not found 

ALLOCATE error 

PUT error 

Nonunique alias name 

If FININS is successful, the task event variable (if specified) is set 
to +1. 





Task 


Event Variable 




-401 




-402 




-403 




-404 




-405 




-406 




-407 




-410 




-411 




-412 
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2.8 EXIT: TERMINATING EXECUTION OF A TASK 

The EXIT directive instructs RSX to terminate execution of the task 
that issues the EXIT. If the issuing task is not fixed in core, the 
core partition of this task becomes available to other tasks. For 
this reason, an EXIT should not be issued until all transfers to or 
from the partition (e.g., I/O transfers, task-to-task transfers, event 
variable settings) have been completed. No event variable can be 
included in the EXIT directive. 

RSX provides protection against premature task EXITs. When any task 
exits, the EXIT Routine checks the transfers-pending count in the task 
partition block node. A nonzero count indicates that the EXITing task 
has pending I/O or mark-time requests. This causes I/O Rundown to be 
invoked. As a result of this operation, the partition in which the 
EXITing task resides does not become free until transfers to or from 
the partition have stopped. 

The EXIT directive can record the amount of processing time used by 
the task that is exiting, provided that the system has XM15 hardware 
and the proper software initialization has occurred. To use this 
feature, the user must develop an exec-mode task that is capable of 
performing the necessary initialization and dump data buffers to a 
mass-storage peripheral device. The steps required to activate the 
task timing software are: 

1. Zero each location in a pair of data buffers. These buffers 
can be anywhere in core, but must be at least four words long 
and should typically have a size that is an integral multiple 
of four words. 

2. Set up a task timing control table as follows: 

Word Name Contents 

EV Task timing event variable 

(must be zero initially) . 

1 STARTl Pointer to first word of 

buffer 1. 

2 ENDl Pointer to last word of 

buffer 1. 

3 START2 Pointer to first word of 

buffer 2. 

4 END2 Pointer to last word of 

buffer 2. 

5 PTR Pointer to next free buffer 

entry (set equal to STARTl 
initially) . The task timing 
software does no error 
checking to ensure the 
validity of the parameters in 
this control table. It is the 
user's responsibility to 
supply the correct data. 

XVM/RSX VIB V-2-19 September 1976 



3. Set absolute location 312 (hereafter referred to as TIMFLG) 
to the address of the task timing control table. The task 
timing routine in the EXIT directive uses TIMFLG as a flag to 
indicate if task timing is to be invoked. Whenever a task 
EXITS, TIMFLG is examined. If it is zero, the task timing 
routine will be bypassed; but if TIMFLG is non-zero, EXIT 
will assume that the task timing routine should be entered. 
Since the user-written buffer-dumping initialization task can 
never tell when EXIT will excunine TIMFLG, this task should 
inhibit interrupts anytime it manipulates that location to 
prevent a race condition. 

When TlilFLG is set, a task EXITs, and there is sufficient 
room in a buffer, the task timing routine will fill the 
appropriate buffer entry with the following data: 

ENTRY WORD CONTENTS 

First half of the task name in 
.SIXBT format 

1 Second half of the task name 
in .SIXBT format 

2 Number of XM clock overflows 
(one unit equals 2.62 seconds) 

3 Number of XM clock ticks above 
overflow count (one unit 
equals 10 microseconds) 

If neither buffer is full, the task timing event varlcible (EV) will 
remain zero. However, EXIT will typically set EV to +1 when buffer 1 
if filled and +2 when buffer 2 is filled. EXIT assumes that when the 
buffer-dumping task has dumped a buffer and reinitialized it to 
zeroes, that task will indicate that the buffer is empty by zeroing 
EV. To avoid a race condition when the buffer-dumping task is 
manipulating EV, it must inhibit interrupts. 

If EXIT determines that both buffers have been filled, it will set EV 
to -1. At this point, no task timing data will as yet have been lost. 
If another task EXITs before a buffer is emptied, EXIT will decrement 
the already negative EV. The buffer-dumping task must then empty a 
buffer, record the number of data entries lost, and set EV to the 
number of the buffer still full. To stop task timing, the buffer 
dumping task need only zero TIMFLG. 

Since the task timing routine can only be invoked when a task EXITs, 
some tasks will seldom, if ever, be timed. Tasks in this category 
include DSK, DSA, IORD,and semipermanent 1/0 handlers such as RF, RK, 
<md RF. Hence, if task timing data is needed for these tasks, the 
user must implement some special code to obtain the required data 
whenever the system is SAVEd and whenever DOS is bootstrapped via the 
relevant MCR Function Tasks. 
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EXIT Directives can be issued by MACRO and FORTRAN programs, but not 
by interrupt service routines. A CPB exists for EXIT, but a standard 
MACRO call has not been implemented. The CAL is issued as follows: 

CAL (10) /TASK EXIT— TERMINATE EXECUTION 

A FORTRAN STOP command can be used to terminate execution of a FORTRAN 
TASK. 

EXITS apply only to calling Tasks. Task exit can be forced via the 
Monitor Console Routine by use of the ABORT function. 

The CPB for this Directive consists simply of the following: 

Word Content s 

CAL function code (10) 
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2.9 FIX: FIXING A TASK IN CORE 

The FIX Directive instructs RSX to FIX an inactive Task in an 
availcOale core partition. This dedicates the partition to that Task 
and provides for faster response to REQUEST, SCHEDULE, RUN, and SYNC 
Directives. FIX does not cause a Task to be executed at the time the 
Directive is issued. The user can optionally include an Event 
Variable. 

This Directive Ccin be issued by MACRO and FORTRAN programs and also by 
interrupt service routines. FIX cannot be issued to an active Task, 
but a Task can FIX itself. In this case, the Directive causes the 
Task to retain control of its partition even after it exits. 
Following is the MACRO call: 



Form: 


FIX name[,ev] 


Where: 


name of Task FIXed is a string 

of one to six .SIXBT characters 
ev is the Event Variable address 


Example : 


FIX SCAN,EV 



and the FORTRAN call: 



Form: 


CALL FIX(nHname[,ev] ) 


Where: 


n is the number of characters in name 
name of Task FIXed is a string of 

one to five ASCII characters 
ev is the integer Event Variable 


Example : 


CALL FIX(4HSCAN,IEV) 



The FIX Directive can also be called from the Monitor Console Routine. 
The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (15) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 



V-2-22 



If the FIX Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause : 



Event Variable Meaning 

-201 Task not in system 

-202 Task is active 

-204 Task is disabled 

-207 Task already FIXed in core 

-210 Partition occupied 

-212 Partition for Task's STL node lost because of 
reconfiguration 

-213 Partition assigned to Task currently being 
reconfigured 

-777 Deque node (for PBDL) unavailable 
(empty pool) 

If the FIX Directive is accepted, the Event Variable (if specified) is 
set to +1 and the Task is flagged as being FIXed in core. The FIXed 
Task is automatically made active at status one to effect loading into 
core. The starting address of this Task is an EXIT Directive in the 
Executive; therefore, the Task exits after it is loaded into core, 
and subsequent EXIT Directives do not free the FIXed partition. Only 
UNFIX can do this. 

Following is an example of a FIX CPB: 

CPB 15 /CAL PARAMETER BLOCK TO 

EV /FIX TASK "19" IN CORE. 

.SIXBT "T9@(a@@" 
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2.10 MARK: SETTING AN EVENT VARIABLE IN THE FUTURE 

The MARK Directive instructs RSX to set an Event Variable to zero and, 
after a specified interval of time, to reset it to a nonzero value and 
to declare a Significant Event. 

Table 2-2 
Reschedule Interval Ranges 



Unit of Time 


Interval Symbol 


Legal Range, Decimal 


Tick 


1 


0-262143 


Second 


2 


0-86400 


Minute 


3 


0-1440 


Hour 


4 


0-24 



This Directive can be issued by MACRO and FORTRAN programs, but not by 
interrupt service routines. MARK Directives affect only the Tasks 
from which they are issued. Following is the MACRO call: 



Form: 



Where ! 



Example ; 



MARK mi,mu,ev 



mi is an integer representing the number of 
units which must elapse before the Event 
Variable is set nonzero (range given in 
Table 2-4) 

mu is 1, 2, 3, or 4 and represents the 
relevant unit of time (see Table 2-4) 

ev is the Event Variable address 



Reset Event Variable TSTEV 5 minutes from now; 
MARK 5, 3, TSTEV 
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and the FORTRAN call: 



Form: 



Where: 



Example ; 



CALL MARK(t,ev) 



t is an array consisting of two integer words 
representing the MARK time interval and unit: 

t(l) = MARK time interval (range given in Table 
2-4) 

t(2) = 1, 2, 3, or 4 and represents the relevant 
unit of time (see Table 2-4) 

ev is the integer Event Variable 



Reset Event Variable lEV 5 minutes from now: 
DIMENSION IT (2) 



IT(1) = 5 
IT (2) = 3 
CALL MARK(IT,IEV) 



The MARK Directive cannot be issued from the Monitor Console Routine. 
The CPB for this directive consists of the following: 



Word 

1 
2 
3 



Contents 
CAL function code (13) 
Event Variable address 
MARK-time interval (see Table 2-4) 
MARK-time units (see Table 2-4) 



If the MARK Directive is rejected by RSX, the Event Variable is set to 
one of the following to indicate rejection and its cause: 



Event Variable 



Meaning 



■203 Directive not Task-issued 

"777 Deque node (for Clock Queue) not 
available (empty pool) 
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If the MARK Directive is accepted, the Event Variable is set to zero, 
and a request to reset the Event Variable is entered in the Clock 
Queue to come due at the appropriate time. Issuing an UNMARK 
Directive can nullify a request. 



Following is an example of a MARK CPB: 



CPB 13 
EV 



.DEC 
170; 
.OCT 



/CAL PARAMETER BLOCK TO CLEAR "EV" 
/AND SET IT TO NONZERO 170 SECONDS 
/FROM NOW. 
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2.11 PARINF: RETURNING PARTITION ADDRESS AND SIZE 

The PARINF Directive instructs RSX to return the base address and size 
of the core partition named in the Directive to the issuing Task. If 
a partition is not specified (if CPB word 2 is zero) , RSX references 
the name of the partition in which the issuing Task runs and stores it 
in CPB words 2 and 3. PARINF Directives are ordinarily not issued by 
user-written code. Therefore no FORTRAN call or standard system MACRO 
has been implemented for PARINF. 

The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (26) 

1 Event Variable address 

2 Partition name (first half) 

3 Partition name (second half) 

4 Address of two-word information buffer 

The partition name is coded in .SIXBT form. 

The information buffer referenced in word 4 contains : 

Word Contents 

Partition base address 

1 Partition size (octal) 

If a PARINF Directive cannot be honored, one of the following Event 
Variables is returned to indicate rejection and its cause: 

Event Variable Meaning 

-203 CAL not Task-issued 

-211 Named partition not in system 

If the PARINF Directive is accepted, the Event Variable is set to | 
cuid the partition information is returned. 
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Following is an example of a PARINF CPB: 



CPB 


26 




EV 




.SIXBT "TDV@@(a" 




PARINF 


/ 




PARINF 


.BLOCK 2 



/FIND OUT WHERE 
/"TDV" PARTITION 
/IS AND STORE 
/THE DATA 

/HERE. 
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2.12 QJOB: QUEUEING A BATCH JOB 

The QJOB directive informs the Batch System that a job is ready to be 
run, whether or not the Batch Processor is in core. The user can 
specify the name of the job to be queued, the LUN from which it comes 
and a series of job characteristics, including: 

Maximum time that the job can run (in minutes) 

Class at which the job can run 

Memory use 

Use of sequencing (run in order of submission) 

Whether the job requires operator availability 

Whether the job file should be deleted after the job runs 

Use of hold mode 

Device and UFD of the job file 

The FORTRAN call for QJOB has the form: 



Form: 



Where ; 



Example! 



CALL QJOB ( lun [ , nHname [ , flags [ , parm [ , ev ] ] ] ] ) 



lun is an integer specifying the (virtual) 

logical unit number on which the job file resides 
n is the number of characters in name 
name of job fi le is a string of _Qji-^_to f ive ASCII 

characters i^HM"e:Sensrorr'is^si^iyl^ JQBl' 
flags is an integer containing the job flags 
parm is an integer containing the job parameters 
ev is the integer event variable 



CALL QJOB (17,4HSCAN,2,31,IEV) 



The CAL parameter block (CPB) for this directive consists of: 
Word Contents 




1 
2 
3 
4 
5 
6 
7 
10 



CAL function code (33) 

Event variable address 

File name (first half) 

File name (second half) 

LUN 

Job flags 

Job parameters 

Login device and unit 

Login UFD 
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The file name and the login UFD are coded in .SIXBT format. The file 
extension of all job files is JOB. CPB words 7 and 10 are not used 
unless bit 7 (UFDPLG) of word 5 is set. 

The contents of CPB word 4 (LUN) are: 

Bit Meaning 

0-8 LUN containing the job file 

9-17 Reserved for the LUN for the listing file 

The job file JUN should be specified as a normal integer in the 
FORTRAN call. QJOB positions the LUN number correctly. 

The contents of CPB word 5 (job flags) are: 



Bit Name 



Meaning 



DLTFLG Delete job file after processing 

1 OPRFLG Operator required to run this job 

2 FRCFLG Force this job to run next 

3 SEQFLG Sequence this job (sequenced jobs are run in 

the order of submittal) 

4 Reserved 

5 HLDFLG Hold this job until it is released by the op- 

erator 

6 CCLFLG Reserved for RSX CCL (concise command lan- 

guage) 

7 UFDFLG Login device, unit and UFD is specified in 

CPB words 7 and 10 
8-17 TIMMSK Job file time limit in minutes (zero implies 

that the default value is used) 

UFDFLG must be clear (zero) in the FORTRAN call. 

The contents of CPB word 6 (job parameters) are: 

Bit Name Meaning 

0-2 CLSMSK Job priority class (0 to 7) 
3-10 Reserved 

11-17 MEMMSK Minimum core needed to run the job (zero in- 
dicates IK; all ones, 127, indicates 128K) 

The contents of CPB word 7 (login device and unit) are: 

Bit Meaning 

0-11 Login device, expressed in .SIXBT format 
12-17 Login unit, expressed in binary 

If CPB word 7 is zero, the system device is implied. If CPB word 10 
(login UFD) is zero, SCR is implied. 
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The login device, unit and UFD in which the job will run is determined 
xn the following way: 

1. If UFDFLG (bit 7 of CPB word 5) is set, the login device, unit 
and UFD are specified by CPB words 7 and 10. If either CPB 
word is zero, appropriate system defaults are used. 

2. If UFDFLG is reset (zero) and the job file resides on a disk, 
the device, unit and UFD in which the job file resides is 
used. 

3. If UFDFLG is reset and the job file does not reside on a disk, 
the system defaults (system disk and SCR) are used. 

If the directive is rejected, the event variable (if specified) is set 
to one of the following values to indicate rejection and the cause: 

Event Variable Meaning 

LUN out of range 

LUN not assigned 

Device unit number out of range 

Too many jobs queued 

Deque node is not available (POOL empty) 

If the directive is accepted, the event variable (if specified) is set 
to #n, where n is the job file sequence number assigned to the job. 
The job file sequence number, used in conjunction with the date of sub- 
mittal, constitutes a unique identifier for each batch job file. 



-101 


-102 


-105 


-106 


-777 
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2.13 QUEUE I/O: QUEUING REQUESTS FOR AN I/O DEVICE 

The QUEUE I/O directive instructs RSX to place an I/O request for a 
particular device unit in a queue of requests for that unit. Entries 
in the queue are ordered according to task priority. Each I/O call 
generates a unique version of the QUEUE I/O directive. The user task 
specifies an operation (e.g., READ, WRITE, REWIND), a logical unit 
number (LUN) corresponding to a physical I/O device unit, and 
additional arguments specific to the operation. 

There are two types of LUNs in RSX: system LUNs and virtual LUNs. A 
block of 25 virtual LUNs for each user is "mapped" to a block of 
system LUNs maintained by RSX. Each user is aware of only his own 
virtual LUNs. The system automatically relates virtual LUNs to system 
LUNs whenever a user requests a task to be run. Refer to Part VII of 
this manual for more information about LUNs. The virtual LUN included 
in the call identifies the physical device for which requests are 
queued. The user task can optionally include an event variable. 

QUEUE I/O requests can be issued by both MACRO and FORTRAN programs. 
No comparable Monitor Console Routine call exists. 

The generalized CAL parameter block (CPB) for all forms of the QUEUE 
I/O directive consists of the following: 

Word Contents 

CAL function code (00) (bits 12 to 17) ; 
I/O function code (bits 3 to 11) 

1 Event variable address 

2 Logical unit number (LUN) 

3 Unique to I/O call 

4 Unique to I/O call 

5 Unique to I/O call 

If the QUEUE I/O directive is rejected by RSX, the event variable (if 
specified) is ordinarily set to one of the following values to 
indicate rejection and the cause: 

Event Variable Meaning 

-101 LUN out of range 

-102 LUN not assigned to a physical device 

-103 Nonresident (not loaded) or noninitialized I/O 
device handler task 

-777 Deque node (for PDVL) not available 
(POOL empty) 
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If the call is accepted, the event variable (if specified) is set to 
zero. A request node is formed and entered in the queue associated 
with the specified LUN at the priority of the task that issues the 
call. The handler task is "triggered" to signal that a request has 
been made. Then control is returned to the user task. The user task 
can subsequently test for completion of the operation by checking for 
a nonzero event variable. 

Each request node has the following format: 



Word 

1 
2 

3 
4 



6 

7 

10 

11 



Contents 

Forward linkage 

Backward linkage 

Task STL node address (zero if the directive is 
not issued at API level 7) 

Task PBDL node address 

Calling task priority in decimal ranqe 1 to 512, 
but ABORT requests issued by lORD (I/O Rundown) 
set the priority to 0. 



I/O function code (bits 9 to 17) ; 
number (bits to 8) 



logical unit 



Event variable address (zero if none specified) 
CPB word 3 (unique to I/O call) 
CPB word 4 (unique to I/O call) 
CPB word 5 (unique to I/O call) 



If the QUEUE I/O directive is issued from an interrupt service routine 
(which runs at API level 0) , words 2 and 3 are zero and word 4 
(priority) is +1. 

Following is an example of a QUEUE I/O CPB: 

CPB 2600 /CAL PARAMETER BLOCK TO READ (I/O FUNCTION 

EV /CODE = 26; CAL FUNCTION CODE = 00) 

4 /FROM LUN #4 

2 /IN lOPS ASCII (MODE 2). 

BUFFER /TRANSFER TO CORE IS TO BEGIN AT 

100 /"BUFFER" AND CONTINUE FOR NO MORE THAN 
/lOO (OCTAL) WORDS. 
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2.14 RAISES: RAISING THE MEMORY-PROTECT BOUND 

The RAISEB Directive instructs RSX to increase the Task size of the 
calling Task and, if the Task is built in USER-mode, to raise its 
memory-protect bound. Because a Task's I/O buffers are created from 
the unused space at the top of a Task's partition. Task size is not 
quxte equivalent to partition size. RAISEB returns to the calling 
Task the highest usable Task address in the partition. This parameter 
xs used by such system Tasks as the Assembler to create symbol table 
space as large as the partition allows. The RAISEB Directive is 
typically used after a Task has reserved I/O buffer space by means of 
the PREAL I/O request. 

The actual raising of the memory-protect bound does not occur until 

the next Significant Event. Therefore it is recommended that a WAIT 

Directive follow the RAISEB Directive to provide the appropriate 
delay. 

No FORTRAN call or standard system MACRO has been implemented for 
RAISEB. 

The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (27) 

1 Event Variable address 

If a RAISEB Directive cannot be honored, the following Event Variable 
is returned to indicate rejection and its cause: 

Event Variable Meaning 

-203 CAL not Task-issued 

If the Directive is accepted, the Event Variable is set to the highest 
usable Task address (relative to the partition base for USER-mode 
Tasks) . 

Following is an example of a RAISEB CPB: 

CPB 27 /RAISE BOUND AND RETURN 
EV /HIGHEST USABLE ADDRESS 
/IN EV. 
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2.15 REQUEST: REQUESTING TASK EXECUTION 

The REQUEST Directive instructs RSX to activate a Task and to REQUEST 
its execution at a specified software priority. Actual time of 
execution depends on partition availability and on Task priority. The 
Task cannot be brought into core from disk until its core partition is 
free. It cannot execute until all higher-priority active Tasks have 
relinquished control. The user can specify a new priority or can 
REQUEST execution at the Task's default priority (assigned during Task 
installation) , He can optionally specify cin Event Variable in the 
Directive. 

Because a priority must be included in the FORTRAN call, priority 
indicates the default priority. This is functionally equivalent to 
omitting the priority specification because Tasks run at API level 7, 
whose priorities range only from 1 to 512. A priority should be 
specified in the MACRO call, but is used to indicate that the 
default priority is intended. 

REQUESTS may be issued by MACRO and FORTRAN programs and by interrupt 
service routines, but a Task cannot REQUEST itself. The MACRO call 
has the following form: 



Form: 



Where: 



Examples ; 



REQUEST name(,p[,ev] ] 



name of Task REQUESTed is a string of one 

to six .SIXBT characters 
p is an integer priority in range 0-512 

decimal 
ev is the Event Variable address 



REQUEST execution of SCAN at the default 

priority of 48: 
REQUEST SCAN,EV 

or 
REQUEST SCAN,0,EV 

or 
REQUEST SCAN, 4 8, EV 

Priority redefined here at 20: 
REQUEST SCAN,20,EV 

Priority redefined here at 20 with no 

Event Variable: 
REQUEST SCAN, 20 
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The FORTRAN call has the following form: 



Form: 


CALL REQST(nHname,p[,ev] ) 


Where: 


n is the number of characters in name 
name of Task REQUESTed is a string of one 

to five ASCII characters 
p is an integer priority in range 0-512 decimal 
ev is the integer Event Variable 


Examples : 


REQUEST execution of SCAN at the default 

priority of 48: 
CALL REQST (4HSCAN,0,IEV) 

or 
CALL REQST (4HSCCAN,48,IEV) 

Priority redefined in FORTRAN program: 

IP = 20 

CATiL REQST (4HSCAN ,IP,IEV) 

REQUEST execution at SCAN's default priority 

with no Event Variable testing: 
CALL REQST (4HSCAN,0) 



The REQUEST Directive can also be called from the Monitor Console 
Routine . 

The CAL Parameter Block (CPB) for this Directive consists of the 
following: 



Word Contents 

CAL function code (01) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 

4 Priority (0-512) 
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If REQUEST is rejected by RSX, the Event Variable (if specified) is 
set to one of the following to indicate rejection and its cause: 



Event Variable Mectning 

-201 Task not in system 

-202 Task is already or still active 

-204 Task is disabled 

-206 Illegal Task priority 

-212 Partition for Task's STL node lost because of 
reconfiguration 

-213 Partition assigned to Task currently being 
reconfigured 

-777 Deque node (for ATL) not available (empty pool) 

If the Directive is accepted, the Event Variable (if specified) is set 
to +1 and the REQUESTed Task is made active at priority p (or at its 
default priority if p is zero) . 

Following is an example of a REQUEST CPBs 

CPB 01 /CAL PARAMETER BLOCK. 

EV /REQUEST EXECUTION OP TASK 

.SIXBT "TKa^e^" /"Tl" NOW. TASK IS TO RUN 
/AT ITS DEFAULT PRIORITY. 
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2.15A REQUEST MAPPED: REQUESTING A TASK WITH MAPPED LUNS 

The REQUEST MAPPED directive is nearly identical to the REQUEST 

directive, with two differences. First, the CAL code for REQUEST 

MAPPED (i.e., the first word of the CPB) is octal 36 instead of 1. 

Second, the REQUEST MAPPED CPB contains an additional word. The new 

CPB word (word 5) follows the word for task run priority (word 4) in 
the CPB. Word 5 of the REQUEST MAPPED CPB contains: 



Bit 
0-8 

9-14 
15-17 



Contents 

LUN offset (i.e., the octal number of the 
system LUN into which virtual LUN-2 is 
mapped) 

MULTIACCESS user number 

Unused 



An example of the REQUEST MAPPED CPB is: 

36 /REQUEST TASK "Tl" WITH 

EV /MAPPED LUNS. MAKE 

.SIXBT "Tl@@@@" /REFERENCES TO LUN-2 GO 

/TO SYSTEM LUN-64 

100000 /(OCTAL 100) 

If the REQUEST MAPPED directive is rejected by RSX, the event variable 
(if specified) is set to one of the same values as described for the 
REQUEST directive, with the following additional possible value: 



Event Variable 



-101 



Meaning 

LUN out of range (indicates that the map requested 
does not fit in the real LUN space) 
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2.16 RESUME: RESUMING TASK EXECUTION 

The RESUME Directive instructs RSX to RESUME execution of a suspended 
Task. All Tasks RESUME at the priority at which they were running 
when suspended. The user can optionally include an Event Variable, 

The Directive can be issued by MACRO and FORTRAN programs and also by 
interrupt service routines. If RESUME is issued by a MACRO program 
and the suspended Task is in EXEC mode, execution of the Task can 
RESUME at any location within the partition. If the address is set to 
zero, the suspended Task RESUMES at the location immediately following 
the SUSPEND Directive. USER-mode Tasks RESUMEd by MACRO programs 
restart at the next location. A FORTRAN call cannot include a 
resumption address, so all Tasks RESUMEd by FORTRAN programs restart 
at the next location. 

The MACRO call has the following form: 



Form: 


RESUME name[,ra[,ev] ] 


Where: 


name of Task RESUMEd is a string of 

one to six .SIXBT characters 
ra is the resumption address 
ev is the Event Variable address 


Example : 


RESUME TSKA,RSTRT,EVA 



A case where a resumption address may be specified symbolically is in 
an interrupt service routine, assembled as part of the Task that it is 
going to RESUME at different locations in the Task depending on the 
nature of the interrupt. 

The FORTRAN call has the following form: 



Form: 


CALL RESUME (nHname [, ev ] ) 


Where: 


n is the number of characters in name 
name of Task RESUMEd is a string of one 

to five ASCII characters 
ev is the integer Event Variable 


Example : 


CALL RESUME {4HTSKA,IEV) 



The RESUME Directive can also be called from the Monitor Console 
Routine . 
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The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (07) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 

4 Resumption address 

Bits 0-2 of the resiimption address (word 4) are ignored. 

If the RESUME Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause : 

Event Variable Meaning 

-30 Specified address for USER-mode Task is 

outside the Task's partition 

-202 Task not active 

-205 Task not suspended 

If the Directive is accepted, the Event Variable (if specified) is set 
to +1, and execution of the indicated Task is RESUMEd (contingent on 
its priority) at the appropriate address. 

The user should be aware of certain limitations on the use of 
resumption addresses. If the issuing Task has been built in USER 
mode, it may not specify a resumption address for the Task to be 
RESUMEd. If the Task to be RESUMEd has been built in USER mode, any 
resumption address for this Task is relative to the partition base. 

Following is an example of a RESUME CPB: 

CPB 07 /CAL PARAMETER BLOCK 

EV /TO RESUME EXECUTION OF 

.SIXBT "T8ia@@@" /TASK "TS" AT LOCATION 
ABC /"ABC". 
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2.17 RUN: ACTIVATING TASK EXECUTION 

The RUN Directive instructs RSX to initiate the execution of a Task at 
a specified software priority and after the passage of some time 
interval, with an optional reschedule interval. Actual time of 
execution depends on Task priority and partition availability. This 
Directive performs the same function as SCHEDULE, except that the time 
of execution is expressed as time from now, not as absolute time of 
day. The user can request that the Task RUN at its default priority 
(assigned during Task installation) or can specify a new priority when 
the Directive is issued. An Event Variable can optionally be 
included. 

Both the initial activation time interval and the reschedule interval 
are expressed in terms of ticks, seconds, minutes, or hours and may 
not exceed one day. Permissible ranges are illustrated in Table 2-2 
below. The initial activation time interval must be included in the 
command line, but the reschedule interval is optional. If the 
reschedule interval is omitted or has a value of 0, the Task is 
executed only once. If the user specifies a reschedule interval of 0, 
he must also specify a reschedule unit, but it does not matter which 
unit he chooses. The Clock Interrupt Service Routine performs Task 
activation and rescheduling. 



Table 2-3 
Reschedule Interval Ranges 



Unit of Time 


Interval Symbol 


Legal Range, Decimal 


Tick 


1 


0-262143 


Second 


2 


0-86400 


Minute 


3 


0-1440 


Hour 


4 


0-24 



Because a priority must be included in the FORTRAN call, priority 
indicates the default priority. This is functionally equivalent to 
omitting the priority specification because Tasks rvm at API level 7, 
whose priorities range only from 1 to 512. A priority should be 
specified in the MACRO call, but is used to indicate that the 
default priority is intended. 
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RUN Directives czui be issued by MACRO eind FORTRAN programs, but not by 
interrupt service routines. A Task may RUN itself. The MACRO call 
has the following form: 



Form: 


RUN name,si,su[,ri,ru[,p(,ev] ] ] 


Where: 


name of Task initiated is a string of 

one to six .SIXBT characters 
si is an integer representing the number of 

units which must elapse before the Task is 

requested (range given in Table 2-2) 
su is 1, 2, 3, or 4 and represents the relevant 

unit of time (see Table 2-2) 
ri is an integer representing the number of 

units which must elapse before the Task is 

rescheduled (range given in Table 2-2) 
ru is 1, 2, 3, or 4 and represents the relevant 

unit of time (see Table 2-2) 
p is an integer priority in range 0-512 decimal 
ev is the Event Variable address 


Examples : 


RUN INITS at a new priority of 512, 5 seconds 
from now, and reschedule it every 10 minutes 
thereafter: 

RUN INITS, 5, 2, 10, 3, 512, EV 

RUN INITS at its default priority with no 

Event Variable testing: 
RUN INITS, 5, 2, 10, 3 

RUN INITS only once: 
RUN INITS, 5, 2, 0,3 

or 
RUN INITS, 5, 2 
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The FORTRAN call has the following form: 



Form; 


CALL RUN(nHname,t,p[,ev]) 


Where: 


n is the number of characters in name 
name of Task initiated is a string of 

one to five ASCII characters 
t is an array consisting of four integer 

words; it represents the initial activation 

time and reschedule interval and units: 
t(l) = initial activation interval (range given 

in Table 2-2) 
t(2) = initial activation units; may be 1, 2, 

3, or 4 (see Table 2-2) 
t{3) = reschedule interval (range given in Table 

2-2) 
t(4) = reschedule units; may be 1, 2, 3, or 

4 (see Table 2-2) 
p is an integer priority in range 0-512 decimal 
ev is the integer Event Variable 


Example : 


RUN INITS at a new priority of 512, 5 seconds 
from now, and reschedule it every 10 minutes 
thereafter; priority set in FORTRAN program: 

DIMENSION IT (4) 

• 
• 

IT(1) = 5 

IT(2) = 2 

IT (3) = 10 

IT(4) = 3 

IP = 512 

CALL RUN(5HINITS,IT,IP,IEV) 
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The RUN Directive can also be called from the Monitor Console Routine. 
The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (03) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 

4 Initial activation interval (see Table 2-2) 

5 Initial activation units (see Table 2-2) 

6 Reschedule interval (see Table 2-2) 

7 Reschedule units (see Table 2-2) 
10 Priority (0-512) 

If the RUN Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause : 



Event Varicible 



-104 



Meaning 
Illegal activation of reschedule units code 



■201 Task not in system 

■203 Directive not Task-issued 

-204 Task is disabled 

-206 Illegal Task priority 

•212 Partition for Task's STL node lost because of 
reconfiguration 

-213 Partition assigned to Task currently being 
reconfigured 

-777 Deque node (for Clock Queue) not available (empty 
pool) 
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If the Directive is accepted, the Event Varicible (if specified) is set 
to +1, and a request to make the indicated Task active is placed in 
the Clock Queue to come due at the appropriate time. 

Following are examples of a RUN CPB: 

CPB 03 /CAL PARAMETER BLOCK TO 

/RUN TASK "T3" 90 SECONDS 
.SIXBT "T3@@@(a" /FROM NOW. NO RE-SCHEDULING. 

.DEC /USE DEFAULT PRIORITY. 

90; 2 /NO EVENT VARIABLE SPECIFIED. 
0;0;0 
.OCT 

CPB 03 /CAL PARAMETER BLOCK TO 

EV /RUN TASK "T4" NOW, AND 
.SIXBT •'T4@@@@" /EVERY TWO MINUTES 

.DEC /FROM NOW ON. TASK IS 

0; 3 /TO RUN AT ITS DEFAULT 

2; 3 /PRIORITY LEVEL. 

.OCT 
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SCHEDULE 



2.18 SCHEDULE: 



SCHEDULING TASK EXECUTION 



The SCHEDULE Directive instructs RSX to SCHEDULE the execution of a 
Task at some future time of day and at a specified software priority, 
with the option to reSCHEDULE it at periodic intervals. Actual time 
of execution depends on Task priority and partition availability. The 
user Ccin SCHEDULE execution at the Task's default priority (assigned 
during Task installation) or can specify a new priority when the 
Directive is issued. An Event Variable can optionally be included. 

The SCHEDULE time is expressed as absolute time of day. The 
reSCHEDULE interval is expressed in ticks, seconds, minutes, or hours. 
The interval begins at the time the Task is first SCHEDULEd to be 
executed and may not exceed one day. Table 2-1 illustrates 
permissible ranges for each interval unit. The SCHEDULE time must be 
included in the command line, but the reSCHEDULE interval is optional. 
If the reSCHEDULE interval is omitted or has a value of 0, the Task is 
executed only once. If the user specifies a reSCHEDULE interval of 0, 
he must also specify a reSCHEDULE unit, but it does not matter which 
unit he chooses. Ticks are intervals equal to the period of the 
real-time clock. The Clock Interrupt Service Routine performs Task 
activation and reSCHEDULing. 



Table 2-4 
Reschedule Interval Ranges 





Cua:siT SVMBo^.N 




Unit of Time 


Interval Symbol 


Legal Range, Decimal 


Tick 


1 


0-262143 


Second 


2 


0-86400 


Winute 


3 


0-1440 


Hour 


4 


0-24 



Because a priority must be included in the FORTRAN call, priority 
indicates the default priority. This is functionally equivalent to 
omitting the priority specification because Tasks run at API level 7, 
whose priorities range only from 1 to 512. A priority should be 
specified in the MACRO call, but is used to indicate that the 
default priority is intended. 
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SCHEDULE Directives can be issued by MACRO and FORTRAN programs, 
not by interrupt service routines. A Task may SCHEDULE itself. 
MACRO call has the following form: 



but 

The 



Form; 



Where! 



Examples '. 



SCHEDULE name, hour, minute, second [,ri,ru[,p[,ev] 1] 



name of Task SCHEDULEd is a string of one to 

six .SIXBT characters 
hour is an integer in range 0-23 decimal 
minute is an integer in range 0-59 decimal 
second is an integer in range 0-59 decimal 
ri is an integer representing the number of 

units which must elapse before the task is 

reSCHEDULEd (range given in Table 2-1) 
ru is 1, 2, 3, or 4, representing the relevant 

unit of time (see Table 2-1) 
P is an integer priority in range 0-512 decimal 
ev identifies the Event Variable address 



SCHEDULE execution of SCAN at 4:30 p.m. at a new 
priority of 200 and reSCHEDULE it every 5 
minutes thereafter: 

SCHEDULE SCAN, 16, 30, 0,5, 3, 200, EV 

SCHEDULE execution at SCAN's default priority 

with no Event Variable testing: 
SCHEDULE SCAN, 16, 30, 0,5, 3 

SCHEDULE execution of ALPHA only once at its 
default priority at 7:15 a.m. with no Event 
Variable testing: 

SCHEDULE ALPHA, 7, 15,0 
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The FORTRAN call has the following form: 



Form: 



CALL SCHED(nHname,t,p[,ev]) 



Where; 



n is the number of characters in name 
name of Task SCHEDULEd is a string of 

one to five ASCII characters 
t is an array consisting of five integer 

words; it represents the SCHEDULE time and 

reSCHEDULE interval and units: 
t(l) = SCHEDULE hour in range 0-23 decimal 
t(2) = SCHEDULE minute in range 0-59 decimal 
t(3) = SCHEDULE second in range 0-59 decimal 
t(4) = reSCHEDULE interval (range given in 

Table 2-1) 
t(5) = reSCHEDULE units; 

(see Table 2-1) 
p is an integer priority in range 0-512 decimal 
ev is the integer Event Variable 



may be 1, 2, 3, or 4 



Examples : 



SCHEDULE execution of SCAN at 4:30 p.m. at a 
new priority of 200 and reSCHEDULE it every 
5 minutes thereafter; priority set in FORTRAN 
program: 

DIMENSION IT (5) 



IT(1) 


= 16 








IT(2) 


= 30 








IT (3) 


= 








IT (4) 


= 5 








IT(5) 


= 3 








IP = 


200 








lEV = 











CALL 


SCHED(4HSCAN< 


,IT 


rIP, 


lEV) 


or 










CALL 


SCHED(4HSCAN, 


,IT 


,200 


,IEV) 



SCHEDULE execution at SCAN's default priority 
with no Event Variable testing (same DIMENSION 
and array assignments) ; 



IP = 

CALL SCHED(4HSCAN,IT,IP) 

SCHEDULE execution only once at SCAN's default 
priority with no Event Variable testing (same 
DIMENSION and array assignments) : 



IT(4) = 
IP = 
CALL SCHED(4HSCAN,IT,IP) 
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The SCHEDULE Directive can also be called from the Monitor Console 
Routine . 

The CPB for this Directive consists of the following: 

Word Contents 

CAL fiinction code (02) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 

4 SCHEDULE hour (0-23) 

5 SCHEDULE minute (0-59) 

6 SCHEDULE second (0-59) 

7 ReSCHEDULE interval (see Table 2-4) 

10 ReSCHEDULE units (see Table 2-4l 

11 Priority (0-512) 

If the SCHEDULE Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause ; 



Event Variable 
-104 



Meaning 
Illegal reschedule unit code 



-201 
-203 
-204 
-206 
-212 

-213 

-777 



Task not in system 

Directive not Task-issued 

Task is disabled 

Illegal Task priority 

Partition for Task's STL node lost because of 
reconfiguration 

Partition assigned to Task currently being 
reconfigured 

Deque node (for Clock Queue) 
not available (empty pool) 



V-2-50 



If the Directive is accepted, the Event Varieible (if specified) is set 
to +1 and a request to maJce the indicated Task active is placed in the 
Clock Queue to come due at the appropriate time. 

Following is an example of a SCHEDULE CPB: 

CPB 02 /CAL PARAMETER BLOCK TO 

EV /SCHEDULE TASK "T2" AT 
.SIXBT "T2(a@(a(a" /17:29:45 HOURS, AND 

.DEC /EVERY FIVE MINUTES 

17; 29; 45 /THEREAFTER. TASK IS 

5; 3 /TO RUN AT PRIORITY 

300 /LEVEL 300. 
.OCT 
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SETJEA 



2.19 SETJEA: INITIALIZING FLOATING-POINT EXIT REGISTER 

The SETJEA Directive instructs RSX to initialize the Floating-Point 
Hardware JMS Exit Address (JEA) register for the issuing Task. This 
Directive is used by the FORTIUS library run-time subroutine that 
handles floating-point hardware errors. SETJEA Directives are 
ordinarily not issued from user-written code. Therefore no FORTRAN 
call or standard system MACRO has been implemented for SETJEA. 

The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (17) 

1 Event Variable address 

2 Subroutine entry address to 
be stored in the JEA 

If the SETJEA Directive cannot be honored, one of the following Event 
Variables is returned to indicate rejection cind its cause: 

Event Variable MecUiing 

-1 No FP hardware on this machine 

-30 JEA address for USER-mode Task 
is outside the Task's partition 

-20 3 CAL not Task-issued 

If the SETJEA Directive is accepted, the Event Variable is set to +1, 
the JEA is initialized, and the address value is saved in the Task's 
Partition Block Node so that the JEA can be restored when necessary. 

Following is an example of a SETJEA CPB: 

CPB 17 /SET JEA TO TRANSFER TO 
EV /ERROR SUBROUTINE WHEN 
ERRSUB /FP ERROR OCCURS. 
/ 

/NOTE — ERROR SUBROUTINE HAS 4 ENTRY POINTS 
/ 
ERRSUB 

JMP OVR /GO TO OVERFLOW 


JMP UND /GO TO UNDERFLOW 


JMP DIV /GO TO DIVIDE 


JMP TRAP /GO TO MEMORY VIOLATION (USER 
/MODE (MEMORY PROTECTION) NOT 
/DISABLED) 
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2.2 SHARE: INVOKING CORE SHARING 



The SHARE directive permits user mode tasks to invoke core memory 
sharing and initially select or change pointers to the area of memory 
associated with the task's External Shared Address Space (ESAS) or to 
deactivate memory sharing entirely. The user can optionally include 
an Event Variable in the Directive. 

This Directive can be issued by MACRO and FORTRAN programs but not by 
Interrupt Service routines. Since memory sharing pertains only to 
user mode tasks, exec mode tasks can issue this Directive but it will 
have no effect on their operation. The user should be aware that a 
task can specify only one shared area of memory at a time, but it can 
subsequently switch shared areas by re-issuing the SHARE Directive 
with other parameters. Note that Cal Parameter Blocks, Event 
Variables, Control Tables, and I/O in general cannot be specified 
within or for a task's ESAS region. Should a task make such an 
attempt, a bad CAL may result or, in the case of an I/O operation, a 
negative event variable will typically be returned. 

The FORTRAN call has the following form: 

Form CALL SHARE (ANAME ,IOFF,LEN, lACC [lEV] ) 

Where: ANAME is a real or double integer array consisting 
of the name of a shareable partition or system 
common block. The name may contain 1 to 5 ASCII 
characters. 

lOFF is an integer constant or variable with the 
offset from the area base address where ESAS is 
to start. 

LEN is an integer constant or variable specifying 
a code indicating the length of ESAS. Either 
0,1,2,3, or 4 are legal values to indicate 
length of (deactivates memory sharing) 256, 
768, 384J3r, or 7936 words respectively. 

lACC is an integer constant or variable specifying 
the desired access to ESAS. Zero indicates 
the task desires read only privileges; one 
indicates a desire for read, write privileges. 

lEV is the Integer Event Variable 

Example: CALL SHARE (P ART , pT , 2 , J? lEV) 
The CPB for the SHARE Directive consists of the following: 



Word 

1 
2 
3 
4 



Contents 
CAL Function Code (35) 
Event Variable Address 

First half of area name in .SIXBIT format 
Second half of area name in .SIXBIT format 
Offset from area base address where ESAS is 
start 
Length of ESAS and access type desired flag 



to 



Word 5 contains two fields for data. Bit J? of this word is zero if 
the task desires read only privileges; Bit is set if a read, write 
capability is desired. Bits 1-17 of word 5 can be set to j2f (to 
deactivate memory sharing), 4J2fJ2f, 14J!fJ?, 74j2fJ?, or 174prjy octal to 
indicate the size of ESAS. 
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If the SHARE directive is accepted, the Event Variable is set to +1 
and memory sharing will be activated for the task. 

If the SHARE directive cannot be honored, one of the following Event 
Variables is returned to indicate rejection and its causes. 

-32 Partition or System Common Block not in system or does 
not permit memory sharing 

-77 Access type desired not consistent with access type 
permitted . 

-1J?4 Offset not a multiple of 4JH0 octal or illegal length 
specified, or base of shared area plus size of ESAS 
plus offset out of bounds. 

-203 Directive not task-issued. 

-213 Partition or System Common currently being 
reconfigured. 

The following is an example of the SHARE CPB. 

CPB 35 /CAL PARAMETER BLOCK TO 

EV /SHARE lAfSfl OCTAL 

.SIXBT "SYS" /WORDS OF "SYS COM" IN 

.SIXBT "COM" /READ/WRITE FASHION 

ipifS? /OFFSET BY Iflflff OCTAL 

4pfl4prj2f /WORDS FROM ITS BASE 
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SPY 
SPYREL 



2.21 SPY AND SPYRKL: EXAMINING CORE LOCATIONS 

The SPY Directive allows both EXEC and USER Tasks to examine or SPY 
core locations anywhere in memory. The user can optionally include an 
Event Variable in the Directive. This Directive can be issued by 
MACRO and FORTRAN programs, but not by interrupt service routines. 
The FORTRAN call has the following form: 



Foinn: 



Where: 



Example i 



CALL SPY { address , value [ , ev] ) 



address is the octal location to be examined 
value is an integer variable which will contain 

the contents of the specified address on return 
ev is the integer Event Variable 



CALL SPY(RSTRT,IVAL,IEV) 



This Directive cannot be called from the Monitor Console Routine, 
The CPB for it consists of the following: 

Word Contents 

CAL function code (31) 

1 Event Variable address 

2 Address to be examined 

3 Returned contents of address to be exeimined 
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If the Directive is rejected, the Event Variable (if specified) is set 
to one of the following to indicate rejection and its cause; 



Event Variable 



Meaning 



-104 
-203 



Parameter error (e.g., invalid address) 
Directive not Task-issued 



If the Directive is accepted, the Event Variable (if specified) is set 
to +1, and the contents of the specified address returned. 

Following is an example of a SPY CPB: 



CPB 31 

EV 

ABC 

VAL 



/CAL PARAMETER BLOCK TO 
/EXAMINE LOCATION ABC AND 
/STORE CONTENTS IN VAL. 



The SPYREL subroutine executes the SPY Directive, but allows a USER 
Task to examine a core location in an area of memory relative to a 
lower bound defined by the contents of SPY 1, location 321. The 
address to be examined is computed by adding the address included in 
the call to the contents of absolute location 321. Location 321 must 
have been set by an EXEC-mode Task. The sum of the two numbers is the 
address whose contents will be placed in the value variable specified 
in the SPYREL call. The user can optionally include an Event Variable 
in the Directive. If the SPY call executed by the subroutine returns 
a negative Event Variable, the subroutine returns control to the 
calling program. Thus it is best to specify the Event Variable. 



SPYREL can be issued only by a FORTRAN 
following form: 



program. 



The call has the 



Form: 



Where: 



Example : 



CALL SPyREL(address,value[,ev]) 



address is the octal number to be added 

to the lower bovmd to compute the octal 

address to be examined 
value is an integer variable which will 

contain the contents of the specified 

address on return 
ev is integer Event Variable 



CALL SPYREL(RSTRT,IVAL,IEV) 
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SPYSET 



2.22 SPYSET: MODIFYING CORE LOCATIONS 



The SPYSET Directive allows both EXEC and USER Tasks to modify core 
locations within bounds specified in the Directive. These locations 
may legally be outside the boundaries of the Task issuing the call. 
The lower bound is defined in absolute location 321 (known as SPYl) 
and the upper bound in location 322 (SPY2) . Both SPYl and SPY2 must be 
initialized by an EXEC-mode Task before a SPYSET is issued. The user 
can optionally include an Event Variable in the Directive. SPYSET 
Directives can be issued by MACRO and FORTRAN programs, but not by 
interrupt service routines. 

A FORTRAN program can issue a SPYSET Directive in the following way: 



Form: 


CATiT. SPYSET (address, value [,ev]) 


Where: 


address is the octal number to be added to 
the lower bound to compute the address to 
be set 

value is an integer to replace the contents 
of the address 

ev is the integer Event Variable 


Example : 


CALL SPYSET (RSTRT,NEWVAL,IEV) 



This Directive cannot be called from the Monitor Console Routine, 
The CPB for it consists of the following: 

Word Contents 

CAL function code (32) 

1 Event Variable address 

2 Address relative to lower bound 

3 Value to replace contents of address 
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If the Directive is rejected, the Event Variable (if specifiedl i« «+• 
to one of the following to indicate rejectioJ a^d its cISsf : 

Event Variable Meaning 

-77 Violation of restricted usage of Directive 
-104 Parameter error (e.g., invalid address) 
-20 3 Directive not Task-issued 

An Event Variable of -77 will be returned if either SPYl or SPY2 has 
not been properly initialized. The Directive will also be rejected 
and an Event Variable of -104 returned if the address to be set is 
greater than the contents of SPY2. If the Directive is accepted, the 
Event Variable (if specified) is set to +1 and the contents of the 
specified address replaced. 

Following is an example of a SPYSET CPB: 

CPB 32 /CAL PARAMETER BLOCK TO 

EV /CHANGE CONTENTS OF LOCATION 

XXY /XXY TO 1001. 

1001 
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SUSPEND 



2.2 3 SUSPEND: SUSPENDING TASK EXECUTION 

The SUSPEND Directive instructs RSX to SUSPEND execution of the 
issuing Task. The Task remains active in its core partition, but 
execution cannot proceed until the RSX Executive receives a RESUME 
Directive for this Task. An Event Variable is not included in the 
Directive. 

Only the Task from which the SUSPEND Directive is issued can be 
SUSPENDed. SUSPEND Directives can be issued by MACRO and FORTRAN 
programs, but not by interrupt service routines. 

A CPB exists for SUSPEND, but a standard MACRO call has not been 

implemented. The SUSPEND Directive cannot be issued via the Monitor 

Console Routine, since a Task can only be suspended by itself and is 

protected against suspension by all other means, including the 
operator. 

The CPB for this Directive consists simply of the following: 

Word Contents 

CAL function code (06) 

The CAL is issued as follows; 

CAL (6) /SUSPEND TASK EXECUTION 

A FORTRAN PAUSE Statement can be used to SUSPEND execution of a 
FORTRAN Task until RESUMEd. 
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2.24 SYNC: SYNCHRONIZING TASK EXECUTION 

The SYNC Directive instructs RSX to make a Task active at some future 
time and at an indicated software priority, with the option to 
reschedule this activation at periodic intervals. Actual time of 
execution depends on Task priority and partition availability. The 
user can request execution at the Task's default priority (assigned 
during Task installation) or can specify a new priority when the 
Directive is issued. An Event Variable can optionally be included. 

This Directive performs the same function as SCHEDULE or RUN, except 
that the SYNChronized time of execution is expressed as a stated 
interval of time after the next tick, second, minute, or hour mark, 
not as absolute time of day. A SYNChronization unit specifies after 
which unit of time the Task is activated. For example, a Task named 
TASKl is scheduled by a program to be run 5 minutes after the 
occurrence of the next hour mark. If it is now 10:58:35, TASKl will 
be SYNChronized at 11:05:00. The length of time that must elapse can 
therefore vary depending on the time of day. The Clock Interrupt 
Service Routine performs Task activation and rescheduling. 

The SYNC Directive is useful in SYNChronizing the execution of a 
number of Tasks, so that peak loading of the system can be avoided. 

Both the initial activation time interval and the reschedule interval 
are expressed in terms of ticks, seconds, minutes, or hours and may 
not exceed one day. Permissible ranges are illustrated in Table 2-3 
below. The initial activation time interval must be included in the 
command line, but the reschedule interval is optional. If si, the 
initial activation interval, is 0, execution of the Task is initiated 
on the next occurrence of the schedule unit. If the reschedule 
interval is omitted or has a value of , the Task is executed only 
once. If the user specifies a reschedule interval of 0, he must also 
specify a reschedule unit, but it does not matter which unit he 
chooses. 



Table 2-5 
Reschedule Interval Ranges 



Unit of Time 


Interval Symbol 


Legal Range, Decimal 


Tick 


1 


0-262143 


Second 


2 


0-86400 


Minute 


3 


0-1440 


Hour 


4 


0-24 



Because a priority must be included in the FORTRAN call, priority 
indicates the default priority. This is functionally equivalent to 
omitting the priority specification because Tasks run at API level 7, 
whose priorities range only from 1 to 512. A priority should be 
specified in the MACRO call, but is used to indicate that the 
default priority is intended. 
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SYNC Directives can be issued by MACRO and FORTRAN programs, but not 
by interrupt service routines. A Task may SYNChronize itself. The 
MACRO call has the following form: 



Form; 



Where! 



SYNC name,sz,si,su[,ri,ru[,p[,ev] ] ] 



Examples 



name of Task initiated is a string of 

one to six .SIXBT characters 
sz is 1, 2, 3, or 4 and represents the 

relevant SYNChronization unit (see 

Table 2-3) 
si is an integer representing the number of 

units which must elapse before the Task is 

initially activated (range given in Table 2-3) 
su is 1, 2, 3, or 4 and represents the 

relevant unit of time (see Table 2-3) 
ri is an integer representing the number of 

units which must elapse before the Task is 

rescheduled (range given in Table 2-3) 
ru is 1, 2, 3, or 4 and represents the 

relevant unit of time (see Table 2-3) 
p is an integer priority in range 0-512 decimal 
ev is the Event Variable address 



SYNChronize execution of FRED at a new priority 
of 20, 9 seconds after the next minute mark 
(i.e., it is now 14:27:47: run Task at 
14:28:09) and reschedule it every 4 minutes 
thereafter: 

SYNC FRED,3,9,2,4,3,20,SYNEV 

SYNChronize execution of SCAN at a new priority 
of 21,10 seconds after the next minute next 
and reschedule it every hour thereafter: 

SYNC SCAN,3,10,2,1,4,21,SYNEV 

SYNChronize execution of FRED only once 

at a new priority of 21, 10 seconds after the 
next minute mark: 

SYNC FRED,3,10,2,21,SYNEV 
or 

SYNC FRED,3,10,2,0,4,21,SYNEV 



V-2-61 



The FORTRAN call has the following form: 



Foxia: 



Where! 



CALL syNC(nHname,t,p[,ev] ) 



n is the number of characters in name 

name of Task initiated is a string of one to 

five ASCII characters 
t is an array consisting of five integer 

words; it represents the SYNChronization unit 

cmd the initial activation and reschedule 

intervals and units; 



t(l) 
or 
t(2) 
t(3) 
or 
t(4) 
t(5) 



= SYNChronization unit; may be 1, 2, 3, 

4 

= initial activation interval 

= initial activation units; may be 1, 2, 



3, 



reschedule interval 

reschedule units; may be 1, 2, 3, or 4 
p is an integer priority in range 0-512 decimal 
ev is the integer Event Variable 



Example : 



SYNChronize execution of FRED at a new priority 
of 20, 9 seconds after the next minute mark, 
and reschedule it every 4 minutes thereafter. 
In the same program, SYNChronize execution of 
SCAN at 21, 10 seconds after the next minute 
mark, cind reschedule it every hour thereafter; 

INTEGER FREDEV,SCANEV,SCANP,FREDP 

DIMENSION IT (5) 



IT(1) 
IT(2) 
IT(3) 
IT(4) 
IT(5) 



3 
9 
2 
4 
3 



FREDEV = 
FREDP = 20 
CALL SYNC (4HFRED, IT, FREDP, FREDEV) 

SCANEV = 

SCANP =21 

IT (2) = 10 

IT(4) = 1 

IT(5) = 4 

CALL SYNC (4HSCAN, IT, SCANP, SCANEV) 
C INSURE BOTH SYNC REQUESTS WERE ACCEPTED 

IF (SCANEV. OR. FREDEV. LT.O) GO TO 10 
C BOTH SYNC REQUESTS WERE ACCEPTED AT THIS POINT 

C REPORT FAILURE OF SYNCS TO BE ACCEPTED TO 
C CONSOLE OPERATOR. 

10 WRITE (3,11) 

11 FORMAT (32H TASKS FRED OR SCAN NOT SYNC 'ED.//) 
STOP 

END 
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The SYNC Directive can also be called from the Monitor Console 
Routine . 

The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (14) 

1 Event Variable address 

2 Task name (first half) 

3 Task name (second half) 

4 SYNC unit (see Table 2-3) 

5 Initial activation interval (see Table 2-3) 

6 Initial activation unit (see Table 2-3) 

7 Reschedule interval (see Table 2-3) 

10 Reschedule unit (see Table 2-3) 

11 Priority (0-512) 

If the Directive is rejected by RSX, the Event Variable (if specified) 
is set to one of the following to indicate rejection and its cause: 

Event Variable Meaning 

-104 Illegal SYNC, activation of reschedule units code 

-201 Task not in system 

-203 Directive not Task-issued 

-204 Task is disabled 

-206 Illegal Task priority 

-212 Partition for Task's STL node lost because of 
reconfiguration 

-213 Partition assigned to Task currently being 
reconfigured 

-777 Deque node (for Clock Queue) not 
available (empty pool) 
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If the Directive is accepted, the Event Variable (if specified) is set 

to +1, and a request to make the indicated Task active is placed in 
the Clock Queue to come due at the appropriate time. 

Following are examples of a SYNC CPB: 

CPB 14 /CAL PARAMETER BLOCK TO 

EV /SYNC TASK "T5" 2.5 MINUTES 

.SIXBT "T5@(a@@" /AFTER THE NEXT HOUR, AND 

.DEC /EVERY 30 MINUTES THEREAFTER. 

4 /TASK IS TO RUN AT PRIORITY 

150; 2 /LEVEL 512. 
30; 3 
512 
.OCT 

CPB 14 /CAL PARAMETER BLOCK TO 

/SYNC TASK "T6" ON THE NEXT 

.SIXBT "T6@@@@" /MINUTE. IT IS TO EXECUTE ONLY 

.DEC /ONCE AT ITS DEFAULT PRIORITY. 

3 /NO EVENT VARIABLE IS SPECIFIED. 
0; 3 
0; 3 

.OCT 
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TSKNAM 



2.25 TSKNAM: RETURNING THE NAME OF THE ISSUING TASK 

The TSKNAM Directive instructs RSX to return the name of the issuing 
Task. One of the most common applications of this Directive is its 
use by the FORTRAN PAUSE Object-Time System routine (OTS) to print a 
Task name in the PAUSE message. TSKNAM Directives are ordinarily not 
issued by user-written code. Therefore no FORTRAN call or standard 
system MACRO has been implemented for TSKNAM. 

The CPB for this Directive consists of the following: 



Word Contents 

CAL function code (25) 

1 Event Varicible address 

2 Task name buffer (first half) 

3 Task name buffer (second half) 



If a TSKNAM Directive cannot be honored, the following Event Varic±)le 
is returned to indicate rejection and its cause: 



Event Variable Meaning 

-203 CAL not Task-issued 



If the TSKNAM Directive is accepted, the Task name will be stored in 
words 2 and 3 of the CPB and the Event Variable will be set as 
follows: 



Bit of Event Variable 

1 
2 
3 
4 
5-6 



8-17 



Meaning 

Cleared upon acceptance of Directive 

Set if task requires Floating Point hardware 

Set if task runs in Bank mode 

Set if task runs in User mode 

Unused and set to zero 

Correspond to XVM mode bits of task's STL 
node (always zeroed for Exec mode tasks) 

Set if task has lOT permission (always zeroed 
for Exec mode tasks) 

Task priority 
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Following is an example of the TSKNAM CPB: 

CPB 25 /REPLACE "XX" WITH 

EV /THE NAME OF THIS 

XX /TASK, I.E., WHO 

XX /AM I? 
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2.26 UNFIX: FRIIEING A CORE PARTITION 

The UNFIX Directive instructs RSX to nullify a FIX Directive, L.&. , to 
free the core partition for use by other Tasks. If a fixed Task is 
active when an UNFIX is issued, the partition is made available as 
soon as the active Task exits. The user can optionally include an 
Event Variable in the Directive. 

This Directive Ceui be issued by MACRO and FORTRAN programs and also by 
interrupt service routines. 

Following is the MACRO call: 



Form: 


UNFIX name[,ev] 


Where: 


name of Task UNFIXed is a string of 

one to six .SIXBT characters 
ev is the Event Variable address 


Example : 


UNFIX SCAN,EV 



and the FORTRAN call: 



Form: 


CALL UNFIX(nHnaine[,ev]) 


Where: 


n is the number of characters in name 
name of Task UNFIXed is a string of 

one to five ASCII characters 
ev is the integer Event Variable 


Example : 


CALL UNFIX (4HSCAN,IEV) 



The UNFIX Directive can also be called from the Monitor Console 
Routine . 

The CPB for this Directive consists of the following: 



Word 

1 
2 
3 



Content s 
CAL function code (16) 
Event Variable address 
Task name (first half) 
Task name (second half) 
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If the UNFIX Directive is rejected by RSX, the Event Variable (if 
specified) is set to one of the following to indicate rejection and 
its cause: 



Event Variable Meaning 

-201 Task not in system 
-207 Task not fixed 

If the UNFIX Directive is accepted, the Event Variable (if specified) 
is set to +1 and the Task is UNFIXed. 

Following is an example of am UNFIX CPB: 

CPB 16 /CAL PARAMETER BLOCK 

EV /TO UNFIX TASK "TIC". 

.SIXBT "T10iaia@" 
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UNMARK 



2.2 7 UNMARK: CANCELLING MARK-TIME REQUESTS 

The UNMARK Directive instructs RSX to cancel all outstanding mark-time 
requests for the Task specified in the call. It exists specifically 
for the use of the I/O Rundown Task and is also employed by the 
Magtape I/O Handler Task. UNMARK Directives are ordinarily not issued 
by user-written code. Therefore no FORTRAN call or standard system 
MACRO has been implemented for UNMARK. 

The CPB for this Directive consists of the following: 

Word Contents 

CAL function code (23) 

1 Event Variable address 

2 Task ncume (first half) 

3 Task name (second half) 

If the Directive is rejected by RSX, the Event Variable is set to the 
following to indicate rejection and its cause: 

Event Variable Meaning 

-201 Task not in system 

If the Directive is accepted, the Event Variable is set to +1. All 
mark-time nodes in the Clock Queue for the specified Task are 
nullified, but not removed from this list. Note that nodes are not 
actually removed from the queue and returned to the "Pool of Empty 
Nodes" until the period of time specified in the appropriate MARK 
Directive has elapsed. It is therefore possible to exhaust the pool 
by issuing too many MARK Directives in a short period of time, even if 
MARKS are followed by UNMARKs. 

Following is an example of an UNMARK CPB: 

CPB 23 /CAL PARAMETER BLOCK 

EV /TO UNr4ARK TASK "T13". 

.SIXBT "T13§@@" 
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2.2 8 WAIT: WAITING FOR THE NEXT SIGNIFICANT EVENT 

The WAIT Directive instructs RSX to suspend execution of the issuing 
Task until the next Significant Event. Until such time, the Task 
remains in its core partition and on the Active Task List, but is 
dormant. Lower-priority Tasks are allowed to run. When the next 
Significant Event occurs, the issuing Task (contingent upon priority) 
resumes at the loOation immediately following the WAIT CAL 
instruction. No Event Variable may be included in the Directive. 

WAIT Directives can be issued by MACRO and FORTRAN programs, but not 
by interrupt service routines. It is the responsibility of the Task 
that issues the Directive to determine the meaning of the Significant 
Event that causes its resumption. A CPB exists for WAIT, but a 
standard MACRO call has not been implemented. The CAL is issued as 
follows : 



CAL (5) 



A^AIT FOR NEXT SIGNIFICANT EVENT. 



A FORTRAN PAUSE statement can be used to suspend execution of a 
FORTRAN Task until a test indicates that the next Significant Event 
has occurred. 

This Directive cannot be called from the Monitor Console Routine. The 
CPB for it consists simply of the following: 



Word 



Contents 



CAL function code (05) 
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WAITFOR 



2.29 WAITFOR: WAITING FOR AN EVENT VARIABLE TO BE SET 

The WAITFOR Directive instructs RSX to examine a specified Event 
Variable; if the Event Variable is zero, WAITFOR suspends execution 
of the Task that issues the Directive until the Event Variable is set 
to a nonzero value, RSX examines the Event Variable every time a 
Significant Event occurs and a high priority Task is unable to 
execute. As soon as a nonzero value is detected, the suspended Task 
is resumed at the priority at which it was previously rvmning. The 
Task is resumed at the instruction immediately following the location 
of the WAITFOR Directive. 

This Directive can be issued by MACRO and FORTRAN programs, but not by 
interrupt service routines. WAITFOR Directives affect only the Tasks 
from which they are issued. Following is the MACRO call: 



Form; 



Where! 



Examples 



WAITFOR ev 



ev is the Event Variable address 



In this example, the MARK Directive 

sets Event Variable MRKEV to zero for 5 
minutes and then resets it to a nonzero value. 
WAITFOR detects that the Event Variable _ is 
zero and suspends Task execution until it is 
reset to a nonzero value (i.e., in 5 minutes). 
Then the Task is resumed at the instruction 
immediately following the WAITFOR: 

MARK 5, 3, MRKEV 

WAITFOR MRKEV 



V~2-71 



and the FORTRAN call: 



Form: 


CALL WAITFR(ev) 


Where: 


ev is the integer Event Variable 


Exaniple : 


See introduction to MACRO example above: 
DIMENSION IT (2) 

• 
• 

IT(1) = 5 
IT(2) = 3 
C lEV WILL AUTOMATICALLY BE CLEARED BY MARK 
CALL MARK (IT,IEV) 
CALL WAITER (lEV) 



The WAITFOR Directive cannot be issued from the Monitor Console 
Routine . 

The CPB for this Directive consists of the following: 



Word 



Contents 



CAL function code (20) 

1 Event Variable address 



The subroutine which follows illustrates the interaction of MARK and 
WAITFOR CPBs: 



DELAY 

DAC MARK+2 
CAL MARK 
CAL WAITF 
JMP* DELAY 

/ 

MARK 13 

EV 

XX 

2 

/ 

WAITF 20 
EV 

/ 

EV 



/SUBROUTINE TO SUSPEND EXECUTION 
/FOR THE NUMBER OF SECONDS 
/INDICATED BY THE CONTENTS OP AC. 



/CAL PARAMETER BLOCK TO CLEAR "EV" 
/THEN SET IT AND DECLARE A 
/SIGNIFICANT EVENT XX SECONDS FROM NOW. 



/CAL PARAMETER BLOCK TO SUSPEND 
/EXECUTION UNTIL "EV" IS SET (WAITFOR) . 

/EVENT VARIABLE. 
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XFRCMD 



2.30 XFRCMD: TRANSFERRING TDV COMMAND LINE 

The XFRCMD directive transfers the lOPS ASCII command line supplied by 
the user and read by the MULTIACESS Monitor to a specified line buffer | 
in the partition of the issuing task. XFRCMD is used by all TDV • 
function tasks. No FORTRAN call or standard system MACRO has been 
implemented for XFRCMD. 

The CPB for XFRCMD consists of the following: 

Word Contents 

CAL function code (37) 

1 Event variable address 

2 TDV task buffer address 

3 TDV task buffer size (octal) 

If the XFRCMD directive cannot be executed, one of the following event 
variables is returned to indicate rejection and the cause: 

Event Variable Meaning 

-16 TDV task buffer too small 

-77 Violation of restricted use of XFRCMD; the 

issuing task is not a TDV function • 

-203 CAL not task-issued 

If the XFRCMD directive is accepted, the command line is transferred 
and the event variable is set to +1. • 

Following is an example of a XFRCMD CPB: 

CPB 37 /TRANSFER THE COMMAND LINE 

EV /TO "BUF". THE BUFFER 

BUF /SIZE IS 34 (OCTAL) WORDS. 
34 
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CHAPTER 3 
SYSTEM MACROS 



System Macros are similar to System Directives but are characterized 
by the following; 

. System Macros are not implemented as CAL instructions; they 
are direct MACRO subroutine calls and, as such, may be executed 
only by Tasks built in EXEC mode. 

. System Macros do not return Event Variable information. 

INTENTRY and INTEXIT are not absolutely required. They are provided 
as a coding convenience and are recommended only when it is necessary 
to save and restore many active system registers. 
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INTENTRY 



3.1 INTENTRY: ENTERING REGISTER SAVE ROUTINE 

The INTENTRY System Macro instructs RSX to enter the Executive's 
Register Save Routine. This routine obtains the current contents of 
all active system registers (e.g., AC, index and limit registers, 
autoincrement registers) and deposits the contents in a save area. 
This area is created by the MACRO Assembler during expansion of the 
INTENTRY System Macro. 

INTENTRY System Macros may be issued only from MACRO interrupt service 
routines. The call itself must be the first instruction in this 
routine. Following is the MACRO call: 



Form: 


INTENTRY entry 


Where: 


entry is the octal entry address (connect 
location) of the interrupt service 
routine. The user must not supply 
the address tag entry because it 
is part of the code generated by this macro 
definition. 


Example : 


INTENTRY CL 



Registers saved by INTENTRY are restored by execution of INTEXIT. 
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INTEXIT 



3.2 INTEXIT: ENTERING REGISTER RESTORE ROUTINE 

The INTEXIT System Macro instructs RSX to enter the Executive's 
Register Restore Routine. This routine restores all active registers 
saved by INTENTRY, debreaks, emd returns to the interrupted Task. 
INTEXIT System Macros can be issued only from MACRO interrupt service 
routines. Following is the MACRO call: 



Form: 


INTEXIT entry 


Where: 


entry is the octal entry address (connect 
location) of the interrupt service routine 


Example : 


Interrupt service routine ADINT (for A/D 
Converter) uses INTENTRY and INTEXIT: 

INTENTRY ADINT /MUST BE PLACED AT THE ENTRANCE 
/ TO THE INTERRUPT ROUTINE. 

! /SECTION TO SERVICE INTERRUPT. 
INTEXIT ADINT /RESTORE REGISTERS, DEBREAK, 
/ AND RETURN TO INTERRUPTED 
/ TASK. 
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CHAPTER 4 
EVENT VARIABLES 



Event Variables are software flags set by RSX for system or other 
Tasks, and are used to indicate the success or failure of the Task's 
operations. Most System Directives provide for an Event Variable in 
the MACRO or FORTRAN call. With few exceptions, inclusion of this 
variable is optional. If the user does specify an Event Variable, a 
code indicating the status of the Directive is normally returned to 
the issuing Task after the request has been processed. This specified 
code is in the following ranges: 

Code Meaning 

+n Directive accepted; n is almost always 1 

Directive pending 

-n Directive rejected: n is a number indicating why 
rejection occurred 

The second CPB word for all Directives except EXIT, WAIT, and SUSPEND 
contains the address of the Event Variable to be set. If the contents 
of this word remain zero, this indicates that the user Task has 
specified no Event Variable to be set by the Directive within it or 
that, for some reason, the Directive request is still pending. 

If the user Task does specify ein Event Variable, it is initially set 
to zero to indicate that the Directive has not yet been processed. 
Once the Directive has been accepted or rejected, the Event Variable 
is set with a nonzero value to indicate either acceptance or rejection 
for a particular reason. In the sections above. Event Variables have 
been described for System Directives to which they apply. Some Event 
Variables are specific to a particular Directive; others are common 
to two or more Directives. Table 4-2 provides a summary of all 
negative Event Variabiles which may be returned to RSX System 
Directives, as well as possible reasons for failure, and Directives to 
which particular Event Variables are returned. Directives are 
abbreviated as follows: 
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Table 4-1 
System Directive Abbreviations 



Abbreviation 



10 

RQ 

SC 

RN 

SY 

CN 

RS 

MT 

UM 

FX 

UF 

DA 

EA 

CI 

DI 

DT 

SJ 

TN 

PI 

RB 

TC 

SP 

SS 

QU 

SH 

EX 

RM 



Directive 



OUEUE I/O 

REQUEST 

SCHEDULE 

RUN 

SYNC 

CANCEL 

RESUME 

MARK 

UNMARK 

FIX 

UNFIX 

DISABLE 

ENABLE 

CONNECT 

DISCONNECT 

DATE 

SETJEA 

TSKNAM 

PARINF 

RAISEB 

XFRCMD 

SPY 

SPYSET 

QJOB 

SHARE 

EXECUTE 

REQUEST 

MAPPED 



Function 



Queue requests for I/O unit 

Request task execution 

Schedule task execution 

Activate task execution 

Synchronize task execution 

Cancel requests for a task 

Resume task execution 

Set event variable in future 

Cancel mark-time requests 

Fix a task in core 

Free a core partition 

Disable a task 

Reenable a task 

Connect to interrupt line 
Disconnect from interrupt line 
Retrieve time and date 

Initialize floating-point exit register 

Return name of issuing task 

Return partition address and size 

Raise memory-protect bound 

Transfer TDV command line 

Examine core locations 

Modify core locations 

Queue a batch job 

Invoke memory sharing 

Request task execution from user disk 

Request a task with mapped LUNs 
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Table 4-2 
Returned Event Variables 



Event 
Variable 


Directive 


Reason 


-1 


SJ 


No floating-point hardware on this machine 


-2 


10 


I/O request aborted 


-16 


TC 


Output word-pair count or input 
buffer-size error 


-26 


CI,DI 


Illegal function for a user-mode task 


-30 


SJ,RS 


Address for user-mode task is outside the 
task partition 


-32 


SH 


Nonexistant system COMMON block or 
partition, or core sharing not permitted 


-77 


TC,SS,SH,RM 


Violation of restricted usage of directive 


-101 


10, RM 


LUN out of range 


-102 


10 


LUN not assigned to a physical device 


-103 


10 


Nonresident or noninitialized I/O device 
handler task 


-104 


SP,SS,SH, 
SY,SC,RN 


Parameter error (in CPB or control table) 


-201 


RQ,SC,RN, 
SY,CN,UM, 
FX,UF,DA, 
EA,EX,RM 


Task not in system 


-202 


RQ,FX,EX 
RS,RM 


Task is active 
Task is inactive 


-203 


SC,RN,SY, 
MT,SJ,PI, 
TC,TN,RB, 
SP,SS,SH,QU 


Directive not task-issued 


-204 


RQ,SC,RN, 
SY,PX,EX,RM 


Task is disabled 


-205 


RS 


Task not suspended 


-206 


RQ,SC,RN, 
SY,EX,RM 


Illegal task priority 


-207 


FX 
UF 


Task already fixed 
Task not fixed 



(Continued on next page) 
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Table 4-2 (Cont.) 
Returned Event Variables 



I 
I 



Event 
Variable 



-210 
-211 
-212 

-213 

-301 
-302 

-401 
-402 
-403 
-404 
-405 
-406 
-407 
-410 
-411 
-412 
-777 



Directive 



FX 

PI 

RQ,SC,RN,SY, 
FX,EA,EX,RM 

RQ,SC,RN,SY, 
FX,EA,EX,SH,RM 

CI,DI 

CI 
DI 

EX 

EX 

EX 

EX 

EX 

EX 

EX 

EX 

EX 

EX 

Most modules 



Reason 



Partition occupied 

Partition not in system 

Partition for task STL node lost because 
of reconfiguration 

Partition or system COMMON block currently 
being reconfigured 

Line number rejected 

Line is connected 
Line is not connected 

Illegal LUN 

HINF error 

Illegal device 

Disk dismounted 

GET error 

File not created 

File not found 

ALLOCATE error 

PUT error 

Nonunigue alias name 

Deque node unavailable (empty pool) 
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APPENDIX A 
THE MACRO DEFINITIONS FILE 



All system MACROS implemented in the RSX system are defined in one of 
the files supplied as part of RSX and known as the MACRO Definitions 
File. This appendix contains definitions for all currently 
implemented standard system MACROS except those used exclusively for 
I/O. 



The following listing summarizes abbreviations used in the 
Definitions File and appears at the beginning of that file. 



MACRO 



/ EDIT #13 

/ 

/ COPYRIGHT 1971,1972,1973 DIGITAL EQUIPMENT CORP., MAYNARD, MASS. 

/ 

/ RSX-15 MACRO DEFINITIONS 14 JUN 73 H. KREJCI 

M. HEBENSTREIT 

UNLESS OTHERWISE SPECIFIED, ALL PARAMETERS 
EXCEPT ADDRESSES ARE GIVEN IN DECIMAL. 

CORE BUFFER ADDRESS 

INTERRUPT CONNECT LOCATION 

CONTROL TABLE ADDRESS 

EVENT VARIABLE ADDRESS 

FILE NAME (1-6 CHARACTERS) 

INTERRUPT LINE NUMBER (OCTAL) 

LOGICAL UNIT NUMBER 

MARK TIME INTERVAL (A TICK THRU A DAY) 

DATA MODE INDICATOR 

MARK TIME UNITS 

RESUMPTION ADDRESS 

RESCHEDULE INTERVAL (0-1 DAY, WHERE IMPLIES 

NO RESCHEDULING) 

RUN PRIORITY (0-512, WHERE IMPLIES DEFAULT 

PRIORITY) 

RESCHEDULE UNITS (H,M,S,T) 

SCHEDULE DELTA (A TICK THRU A DAY) 

SCHEDULE HOURS (0-23) 

CORE BUFFER SIZE (OCTAL) 

SCHEDULE MINUTES (0-59) 

SCHEDULE SECONDS (0-59) 

SCHEDULE DELTA UNITS (H,M,S,T) 

SYNCHRONIZATION UNIT (H,M,S,T) 

TASK NAME (1-6 CHARACTERS) 

FILE NAME EXTENSION (1-3 CHARACTERS) 

UNIT NUMBER OF DISK 



/ 




/ 




/ 


ABREVIATIONS — 


/ 




/ 




/ 


BUFF 


/ 


CL 


/ 


CTB 


/ 


EV 


/ 


FLNAM 


/ 


LN 


/ 


LUN 


/ 


MI 


/ 


MODE 


/ 


MU 


/ 


RA 


/ 


RI 


/ 


RP 


/ 


RU 


/ 


SD 


/ 


SH 


/ 


SIZE 


/ 


SM 


/ 


ss 


/ 


su 


/ 


sz 


/ 


TASNAM 


/ 


EXT 


/ 


UNIT 



V-A-1 



/ TYPE DISK TYPE: 2 — RF, 3 — RP, 24 — RK, — SYSTEM 
DISK 

/ 

H=4 /HOURS INDICATOR 

M=3 /MINUTES INDICATOR 

S=2 /SECONDS INDICATOR 

T=l /TICKS INDICATOR 

/ 

.INH=705522 /INTERRUPT INHIBIT lOT 

.ENG=705521 /INTERRUPT ENABLE lOT 

/ 

SAVE=131 /SAVE ENTRY POINT (IN SCOM) 

REST=134 /RESTORE ENTRY POINT (IN SCOM) 



A.l REQUEST: REQUESTING TASK EXECUTION 

.DEFIN REQUEST,TN,RP,EV 

CAL .+2 

JMP .+6 

01 

EV+0 

..=.; .SIXBT "TN" 

0; .LOC ..+2 

.DEC 

RP+0 

.ENDM 



A. 2 SCHEDULE: SCHEDULING TASK EXECUTION 

.DEFIN SCHEDULE, TN,SH,SM,SS,RI,RU,RP,EV 

CAL .+2 

JMP .+13 

02 

EV+0 

..=.; .SIXBT "TN" 

0; .LOG ..+2 

.DEC 

SH; SM; SS 

RI+0 

RU+0 

RP+0 

.ENDM 



A. 3 RUN: ACTIVATING TASK EXECUTION 

.DEFIN RUN,TN,SD,SU,RI,RU,RP,EV 

CAL .+2 

JMP .+12 

03 

EV+0 

..=.; .SIXBT "TN" 

0; .LOC ..+2 
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.DEC 
SD; SU 

RI+0 
RU+0 
RP+0 

.ENDM 



A. 4 SYNC; SYNCHRONIZING TASK EXECUTION 

.DEFIN SYNC,TN,SZ,SD,SU,RI,RU,RP,EV 

CAL .+2 

JMP .+13 

14 

EV+0 

..=.; .SIXBT "TN" 

0; .LOC ..+2 

.DEC 

SZ; SD; SU 

RI+0 

RU+0 

RP+0 

.ENDM 



A. 5 CANCEL: CANCELLING REQUESTS FOR A TASK 

.DEFIN CANCEL, TN,EV 

CAL .+2 

JMP .+5 

04 

EV+0 

..=.; .SIXBT "TN" 

0; .LOC ..+2 

.ENDM 



A. 6 SUSPEND: SUSPENDING TASK EXECUTION 

.DEFIN SUSPEND 
CAL (6) 
.ENDM 



A. 7 RESUME: RESUMING TASK EXECUTION 

.DEFIN RESUME,TN,RA,EV 

CAL .+2 

JMP .+6 

07 

EV+0 

..=,; .SIXBT "TN" 

0; .LOC ..+2 

RA+0 

.ENDM 
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A. 8 MARK: SETTING AN EVENT VARIABLE IN THE FUTURE 

.DEFIN MARK,MI,MU,EV 

CAL .+2 

JMP .+5 

13 

EV 

.DEC; MI; MU 

.ENDM 



A. 9 WAITFOR: WAITING FOR AN EVENT VARIABLE TO BE SET 

.DEFIN WAITFOR, EV 

CAL .+2 

JMP .+3 

20 

EV 

.ENDM 



A. 10 WAIT: WAITING FOR THE NEXT SIGNIFICANT EVENT 

.DEFIN WAIT 
CAL (5) 

.ENDM 



A. 11 EXIT: TERMINATING EXECUTION OF A TASK 

.DEFIN EXIT 
CAL (10) 

.ENDM 



A. 12 CONNECT: CONNECTING TO AN INTERRUPT LINE 

.DEFIN CONNECT, LN,CL,EV 

CAL .+2 

JMP .+5 

11 

EV+0 

LN 

CL 

.ENDM 
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A. 13 DISCONNECT; DISCONNECTING FROM AN INTERRUPT LINE 

.DEFIN DISCONNECT, LN,CL,EV 

CAL .+2 

JMP .+5 

12 

EV+0 

LN 

CL 

.ENDM 



A. 14 DISABLE: DISABLING A TASK 

.DEFIN DISABLE,TN,EV 

CAL .+2 

JMP +5 

21 

EV+0 

..=.j .SIXBT "TN" 

O; .LOG ..+2 

.ENDM 



A. 15 ENABLE: REENABLING A TASK 

.DEFIN ENABLE,TN,EV 

CAL .+2 

JMP .+5 

22 

EV+0 

..=.; .SIXBT "TN" 

0; .LOC ..+2 

.ENDM 



A. 16 FIX: FIXING A TASK IN CORE 

.DEFIN FIX,TN,EV 

CAL .+2 

JMP .+5 

15 

EV+0 

..=.; .SIXBT "TN" 

O; .LOC ..+2 

.ENDM 



A. 17 UNFIX: FREEING A CORE PARTITION 

.DEFIN UNFIX, TN,EV 
CAL .+2 
JMP .+5 
16 



V-A-5 



EV+0 

..=.; .SIXBT "TN" 

O; .LOG .,+2 

.ENDM 



A. 18 DATE: RETRIEVING TIME AND DATE 



.DEFIN DATE, MON, DAY, YEAR, HRS,MIN, SEC 


CAL 


.+2 


JMP 


.+11 


24 









MO 




DA 




YR 




HH 




MM 




SS 




LAC 


MO 


DAC 


MON 


LAC 


DA 


DAC 


DAY 


LAC 


YR 


DAC 


YEAR 


LAC 


HH 


DAC 


HRS 


LAC 


MM 


DAC 


MIN 


IJVC 


SS 


DAC 


SEC 


.ENDM 



A. 19 INTENTRY: ENTERING REGISTER SAVE ROUTINE 

.DEFIN INTENTRY, CL 
CL 
DBA 

JMS* (SAVE) 
.REPT 24 

.ENDM 



A. 20 INTEXIT: ENTERING REGISTER RESTORE ROUTINE 



.DEFIN INTEXIT, CL 
LAC (CL) 
JMP* (REST) 
.ENDM 
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APPENDIX B 
REGISTERS SAVED DURING SAVE AND RESTORE OPERATIONS 



Whenever the Executive switches control from one task to another, the 
registers listed below are saved for the outgoing task and restored 
for the incoming task if both tasks are in exec mode. The reentrant 
registers (Rl to R6) and the autoincrement registers (XIO to X17) are 
not saved or restored for user-mode tasks. Interrupt service routines 
can use the INTENTRY and INTEXIT system macros to do the same thing, 
except that the MM register, XM clock values and the floating-point 
hardware registers are not saved or restored. 



The registers saved and restored are: 

AC buffer 

XR buffer 

LR buffer 

MQ buffer 

SC buffer 

Rl buffer 

R2 buffer 

R3 buffer 

R4 buffer 

R5 buffer 

R6 buffer 

XIO buffer 

Xll buffer 

X12 buffer 

X13 buffer 

X14 buffer 

X15 buffer 

X16 buffer 

X17 buffer 

L20 buffer 

EPA buffer 

FMAl buffer 

FMA2 buffer 

FMQl buffer 

FMQ2 buffer 

JEA buffer 

MM register buffer 

XM clock overflows 

XM clock ticks (above overflows) 
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APPENDIX C 
.SIXBT CHARACTER SET 



.SIXBT notation is employed to identify Task names in most System 
Directives described in this manual. .SIXBT denotes 6-bit ASCII 
characters, formed by truncating the leftmost bit of the corresponding 
7-bit character. The following table supplies legal characters and 
codes for .SIXBT notation. 



Printing 


7-bit 


.SIXBT 


Printing 


7-bit 


.SIXBT 


Character 


ASCII 




Character 


ASCII 




§ 


100 


00 


Form Feed 


014 




A 


101 


01 


Carriage Return 


015 




B 


102 


02 


Rubout 


177 




C 


103 


03 


(Space) 


040 


40 


D 


104 


04 


I 


041 


41 


E 


105 


05 


n 


042 


42 


F 


106 


06 


# 


043 


43 


G 


107 


07 


$ 


044 


44 


H 


110 


10 


% 


045 


45 


I 


111 


11 


& 


046 


46 


J 


112 


12 


• 


047 


47 


K 


113 


13 


( 


050 


50 


L 


114 


14 


) 


051 


51 


M 


115 


15 


* 


052 


52 


N 


116 


16 


+ 


053 


53 





117 


17 


t 


054 


54 


P 


120 


20 




055 


55 


Q 


121 


21 


• 


056 


56 


R 


122 


22 


/ 


057 


57 


S 


123 


23 





060 


60 


T 


124 


24 


1 


061 


61 


U 


125 


25 


2 


063 


62 


V 


126 


26 


3 


063 


63 


W 


127 


27 


4 


064 


64 


X 


130 


30 


5 


065 


65 


Y 


131 


31 


6 


066 


66 


Z 


132 


32 


7 


067 


67 


[ 


133 


33 


8 


070 


70 


\ 


134 


34 


9 


071 


71 


] 


135 


35 


• 
• 


072 


72 


+ 


136 


36 


• 


073 


73 


-*- 


137 


37 


< 


074 


74 


Null 


000 




= 


075 


75 


Horizontal Tab 


oil 




> 


076 


76 


Line Feed 


012 




? 


077 


77 


Vertical Tab 


013 
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INDEX 



Alias-execute option, 2-18 

API lines, 2-5 

Automatic priority interrupt 

(API) , 2-4 
AUTORM, 2-17 



Event variables, 4-1 

returned, 4-3 
Examining core locations, 2-55 
EXECUTE, 2-16 
EXIT, 2-19 
Exit Processor, MULTIACCESS, 1- 



Batch job, 

queuing, 2-29 



CAL, 

dispatch routine, 1-2 

function code, 1-2 

instructions, 1-1 

service routines, 1-2 
CAL parameter block (CPB) , 1-1 
CANCEL, 2-2 
Cancelling mark-time requests, 

2-69 
Cancelling task requests, 2-2 
Character set, .SIXBT, C-1 
CONNECT, 2-4 
Connecting to interrupt line, 

2-4 
Conventions, directive, 1-3 
Core locations, 

examining, 2-55 

modifying, 2-57 
Core partition, freeing, 2-67 
Core sharing, 2-53 
CPB word, 4-1 



FIX, 2-22 

Fixing a task, 2-22 

Floating-point exit register, 

2-52 
Freeing core partition, 2-67 
Function of system directives, 

1-1 



Initializing floating-point exit 

register, 2-52 
INTENTRY, 3-1, 3-2 
Interval ranges, 2-24, 2-42, 2-60 
INTEXIT, 3-1, 3-3 
Interrupt line, 

connecting to, 2-4 

disconnecting, 2-12 
Introduction, 1-1 
Invoking core sharing, 2-53 



LUN-3, 1-3 

LUN mapping, 2-34 



DATE, 2-8 

Deferred-execute option, 2-18.1 
Directive errors, 1-2 
DISABLE, 2-10 
Disabling a task, 2-10 
DISCONNECT, 2-12 
Disconnecting from an interrupt 
line, 2-12 



Macro definitions file, A-1 
Mapped LUNs, 2-35.1 
MARK, 2-24 
Memory-protect bound, 

raising, 2-36 
Modifying core locations, 2-57 
MULTIACCESS Exit Processor, 1-3 



ENABLE, 2-14 

Entering register restore 

routine, 3-3 
Entering register save routine, 

3-2 
Errors, directive, 1-2 
Event variable, 1-2 

setting, 2-24 
' waiting for, 2-71 



OTS, 2-65 



PARINF, 2-27 
Partition, 

address, 2-27 

size, 2-27 
Processing a directive, 1-2 
Program interrupt (PI) , 2-4 
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INDEX (CONT.) 



QJOB, 2-29 
QUEUE I/O, 2-34 
Queuing batch job, 2-29 
Queuing I/O device requests, 
2-34 



System directives, 2-1 

table of, 1-4 
System macros, 3-1 



RAISEB, 2-36 

Raising memory-protect bound, 

2-36 
Reenabling task, 2-14 
Register restore routine, 3-3 
Register save routine, 

entering, 3-2 
Registers, B-1 
REQUEST, 2-37 
REQUEST MAPPED, 2-35.1 
Requesting a task with mapped 

LUNs, 2-35.1 
Requesting task execution from 

user disk, 2-16 
Reschedule interval ranges, 

2-24, 2-42, 2-60 
Restore operations, B-1 
RESUME, 2-40 

Retrieving time and date, 2-8 
Returned event variables, 4-3 
Returning name of issuing task, 

2-65 
Returning partition address and 

size, 2-27 
RUN, 2-42 



Task, 

activating execution, 2-42 
disabling, 2-10 
fixing, 2-22 
reenabling, 2-14 
requesting execution, 2-37 
requesting execution from user 

disk, 2-16 
resuming execution, 2-47 
returning name of, 2-65 
scheduling execution, 2-47 
size, 2-36 

suspending execution, 2-59 
synchronizing execution, 2-60 
terminating execution, 2-19 

Task Termination Notice Request 
List (TNRL) , 1-3 

Terminating task execution, 2-19 

TDV command line, 
transferring, 2-73 

TIMFLG, 2-20 

INTERN, 1-3 

Transferring 
2-73 

TSKNAM, 2-6 5 



TDV command line, 



Save operations, 
registers, B-1 
SCHEDULE, 2-47 

Scheduling task execution, 2-47 
SETJEA, 2-52 

Setting an event variable, 2-24 
SHARE, 2-53 

.SIXBT character set, C-1 
SPY, 2-55 
SPYREL, 2-55 
SPYSET, 2-57 
SUSPEND, 2-59 

Suspending task execution, 2-59 
SYNC, 2-60 
Synchronizing task execution, 

2-60 
System directive abbreviations, 

4-2 



UNFIX, 2-67 
UNMARK, 2-69 



Virtual LUNs, 2-18, 2-34 



WAIT, 2-70 
WAITFOR, 2-71 

Waiting for event variable, 2-71 
Waiting for next significant event, 
2-70 



XFRCMD, 2-73 
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